CloudStack rebuilds the libvirt domain XML on every VM start, which means
persistent QEMU dirty bitmaps don't survive a stop/start cycle. Rather
than hooking into the VM start lifecycle (intrusive across the
orchestration layer), this commit handles the missing bitmap *lazily* at
the next backup attempt:

  nasbackup.sh
    - When -M incremental is requested, the script first checks
      `virsh checkpoint-list` for the parent bitmap. If absent, it
      recreates the checkpoint on the running domain so libvirt accepts
      the <incremental> reference. The next incremental will be larger
      than usual (it captures all writes since recreate, not since the
      previous incremental) but is correct; subsequent ones return to
      normal size.
    - On recreation, emits BITMAP_RECREATED=<name> on stdout for the
      orchestrator to record.

  BackupAnswer
    + bitmapRecreated field surfaced from the agent.

  LibvirtTakeBackupCommandWrapper
    - Strips BITMAP_RECREATED= line from stdout before size parsing.
    - Sets answer.setBitmapRecreated(...).

  NASBackupChainKeys
    + BITMAP_RECREATED key for backup_details.

  NASBackupProvider
    - When the agent reports a recreated bitmap, persists it under
      backup_details and logs an info-level message so operators can
      correlate larger-than-usual incrementals with VM restarts.

This satisfies the bitmap-loss-on-VM-restart concern from the RFC review
without touching VirtualMachineManager / StartCommand / agent lifecycle.

Refs: apache#12899

Two changes that together let an incremental NAS backup be restored
without manual chain assembly:

  scripts/vm/hypervisor/kvm/nasbackup.sh
    - qemu-img rebase now writes a backing-file path that is RELATIVE to
      the new qcow2's directory (e.g. ../<parent-ts>/root.<uuid>.qcow2)
      rather than the absolute path on the current mount point. NAS mount
      points are ephemeral (mktemp -d), so an absolute reference would
      not resolve when the backup is re-mounted at restore time. Relative
      references are resolved by qemu-img against the file's own
      directory, so the chain stays valid no matter where the NAS is
      mounted next.
    - Verifies the parent file exists on the NAS before rebasing.

  LibvirtRestoreBackupCommandWrapper
    - For file-based primary storage (local, NFS-file), the existing
      code rsync'd the source qcow2 to the volume. That copies only the
      differential blocks of an incremental, leaving a volume whose
      backing-file reference points at a path the primary storage host
      doesn't have. Now: detect a backing-chain via qemu-img info JSON
      and flatten via 'qemu-img convert -O qcow2', which follows the
      chain and produces a self-contained qcow2. Full backups continue
      to use rsync (faster, no chain to flatten).
    - The block-storage path (RBD/Linstor) already used qemu-img convert
      via the QemuImg helper, which auto-flattens chains, so that path
      needed no change.

Refs: apache#12899

Adds the delete-with-chain-repair semantics agreed in the RFC review:

  scripts/vm/hypervisor/kvm/nasbackup.sh
    - New '-o rebase' operation: rebases an existing on-NAS qcow2 onto
      a new backing parent. Uses a SAFE rebase (no -u) so the target
      absorbs blocks of the about-to-be-deleted parent before the
      backing pointer is moved up to the grandparent. Writes the new
      backing reference relative to the target's directory so it
      survives mount-point changes.
    - New CLI flags --rebase-target, --rebase-new-backing (both passed
      mount-relative).

  RebaseBackupCommand + LibvirtRebaseBackupCommandWrapper
    - New agent command that wraps the script's rebase operation. The
      provider sends one of these per child that needs re-pointing.

  NASBackupProvider.deleteBackup
    - Now plans the chain repair before touching files via
      computeChainRepair():
        * No chain metadata     -> single-file delete (legacy behaviour)
        * Tail incremental      -> single delete, no rebase
        * Middle incremental    -> rebase immediate child onto our
                                   parent, then delete; shift
                                   chain_position of all later
                                   descendants by -1
        * Full with descendants -> refuse unless forced=true; with
                                   forced=true delete full + every
                                   descendant newest-first
    - Updates parent_backup_id, chain_position metadata in
      backup_details after each rebase so the model in the DB matches
      the on-disk chain.

This implements the cascade-delete behaviour requested in @abh1sar's
review point apache#7.

Refs: apache#12899

Adds five new test cases to test_backup_recovery_nas.py covering the
end-to-end behaviour of the incremental NAS backup feature:

  * test_incremental_chain_cadence
      - Sets nas.backup.full.every=3, takes 5 backups, verifies the
        type pattern is FULL, INC, INC, FULL, INC.

  * test_restore_from_incremental
      - FULL + 2 INCs, each with a marker file. Restores from the
        latest INC and verifies all three markers are present
        (i.e. qemu-img convert flattened the chain correctly).

  * test_delete_middle_incremental_repairs_chain
      - Builds FULL, INC1, INC2; deletes INC1 (no force needed);
        restores from the surviving INC2 and verifies that markers
        from FULL, INC1 (which was deleted), and INC2 are all present
        — proving the rebase merged INC1's blocks into INC2.

  * test_refuse_delete_full_with_children
      - Verifies plain delete of a FULL that has children fails, and
        delete with forced=true succeeds and removes the whole chain.

  * test_stopped_vm_falls_back_to_full
      - Sets cadence to 2, takes one backup (FULL), stops the VM,
        triggers another (cadence would say INC). Verifies the second
        backup is recorded as FULL because the agent fell back when
        backup-begin couldn't run on a stopped VM.

All tests restore nas.backup.full.every to 10 in finally blocks.

Refs: apache#12899

…wrapper

Address abh1sar review on PR apache#13074 (nasbackup.sh:155, :193, :358; LibvirtTake
BackupCommandWrapper.java:124). The script was carrying caller-side policy:
arg validation, fallback decisions, and stdout markers that the wrapper had to
parse out before the size-parsing logic could run. Move that policy into Java
and use dedicated exit codes for the signals the wrapper needs.

Script (scripts/vm/hypervisor/kvm/nasbackup.sh):
* Drop the per-mode required-args checks (the wrapper now pre-validates).
* Replace the INCREMENTAL_FALLBACK stdout marker with exit code 21
  (EXIT_INCREMENTAL_UNSUPPORTED): emitted when the running-VM path can't
  re-register the parent checkpoint, and when the stopped-VM path was asked
  for incremental. The wrapper retries the script as a full backup and sets
  incrementalFallback on the BackupAnswer.
* Replace the BITMAP_CREATED stdout marker with exit code 22
  (EXIT_BITMAP_NOT_SEEDED), emitted only by the stopped-VM path when
  qemu-img bitmap --add failed for every source disk. Backup file is valid
  but no usable bitmap exists on the host; wrapper records bitmapCreated=null
  so NASBackupProvider clears active_checkpoint_id and the next backup starts
  a fresh full chain. Running-VM success path no longer needs a marker —
  libvirt's backup-begin atomically creates the checkpoint.

LibvirtTakeBackupCommandWrapper.java:
* Pre-validate incremental args (mode-vs-bitmapNew/Parent/parentPaths) before
  invoking the script. Returns a failed BackupAnswer on missing args, keeping
  the script agnostic to caller policy.
* Extract runBackupScript() so the same code can fire the retry-as-full after
  EXIT_INCREMENTAL_UNSUPPORTED without duplicating arg assembly.
* On EXIT_INCREMENTAL_UNSUPPORTED + requestedMode==incremental, re-invoke
  with mode=full and only --bitmap-new (drop --bitmap-parent/--parent-paths);
  set incrementalFallback=true on the eventual answer.
* On EXIT_BITMAP_NOT_SEEDED, treat as success but set bitmapCreated=null.
* Drop the stdout-marker stripping loop (markers no longer emitted), and the
  separate BITMAP_CREATED parsing — bitmapCreated mirrors command.getBitmapNew()
  unless the not-seeded exit code says otherwise.

NASBackupProvider.java:
* Refresh the two comment blocks that referenced the old BITMAP_CREATED= stdout
  signal to describe the new exit-code path. No behaviour change in this file.

…bled (apache#13074)

Addresses abh1sar review: with the incremental feature off, chain/checkpoint
metadata was still written to backup_details/vm_instance_details. Introduce a
distinct legacy-full mode so the feature-off path stays byte-for-byte legacy:

- decideChain returns legacyFull() when nas.backup.incremental.enabled is off:
  no bitmap generated, no chain id, no parent paths.
- takeBackup persists no chain metadata and does not touch active_checkpoint_id
  for legacy-full backups.
- TakeBackupCommand mode carries "legacy-full"; the KVM wrapper accepts it
  (no bitmap/chain args) and forwards -M legacy-full to nasbackup.sh, which
  already maps it to make_checkpoint=0.

Updates the disabled-switch unit test to assert legacy-full + null bitmap/chain.

…cks (apache#13074)

Per abh1sar review:
- Remove the unused rebase_backup() operation (-o rebase), its --rebase-target/
  --rebase-new-backing arguments and REBASE_* variables — no longer called from
  the orchestrator.
- Restore unconditional sanity_checks(): the QEMU/libvirt version check ran for
  every operation before; gating it to backup+MODE was incorrect and unrelated
  to incremental backups.

…ted dump (apache#13074)

Per abh1sar review: libvirt's --redefine only needs the checkpoint name and a
creationTime (the value need not be accurate — checkpoints are ephemeral), so
synthesize a minimal <domaincheckpoint> on the fly instead of persisting the
full checkpoint-dumpxml next to each backup. Removes the per-backup
<bitmap>.checkpoint.xml file.

Verified on libvirt 10: create checkpoint -> delete its metadata (simulating a
VM restart that wipes the registry while the bitmap persists on the qcow2) ->
redefine from the minimal XML succeeds and re-registers the checkpoint.

(The EXIT_INCREMENTAL_UNSUPPORTED removal / inline-fallback simplification is a
separate follow-up pending the fallback-signal design.)

…lling (apache#13074)

Per abh1sar round-2 review:
- When the parent checkpoint can't be re-registered, fall back to a full backup
  in place (effective_mode=full) and emit an INCREMENTAL_FALLBACK marker on
  stdout, instead of exiting EXIT_INCREMENTAL_UNSUPPORTED for a caller-driven retry.
- Remove the stopped-VM incremental guard — the orchestrator never sends
  incremental mode for a stopped VM.
- bitmap --add failure now fails the backup (instead of EXIT_BITMAP_NOT_SEEDED
  silently degrading future backups to full), surfacing the underlying problem.
- Drop EXIT_INCREMENTAL_UNSUPPORTED / EXIT_BITMAP_NOT_SEEDED from the script.

LibvirtTakeBackupCommandWrapper: remove the re-invoke-as-full retry and the two
exit-code constants; detect the INCREMENTAL_FALLBACK stdout marker (recording
incrementalFallback) and strip it before parsing the backup size.

… the qcow2 (apache#13074)

Per abh1sar review (item 3): the VM's active checkpoint/bitmap can be absent from
the qcow2 after a migration even though the orchestrator says it should be there,
which previously made the incremental backup-begin fail hard. Before building the
incremental, probe the running disk via QMP query-block; if the parent bitmap is
not present, fall back to a full backup in place (emit INCREMENTAL_FALLBACK so the
wrapper records it as full) instead of failing.

Verified on a real CirrOS VM (libvirt 10): bitmap present -> true incremental
(marker=0); bitmap absent -> full backup (marker=1, full-size output, rc=0).