### Install virtnbdbackup from source

Source: https://abbbi.github.io/virtnbdbackup

Clone the repository and install the package using pip.

```bash
 git clone https://github.com/abbbi/virtnbdbackup && cd virtnbdbackup
 pip install .
```

--------------------------------

### QEMU guest agent warning

Source: https://abbbi.github.io/virtnbdbackup

Example warning message displayed when the QEMU guest agent is unavailable.

```text
WARNING [..] Guest agent is not responding: QEMU guest agent is not connected
```

--------------------------------

### Backup directory structure

Source: https://abbbi.github.io/virtnbdbackup

Example of the file structure generated within a backup target directory.

```text
/tmp/backupset/vm1
├── backup.full.05102021161752.log
├── backup.inc.05102021161813.log
├── checkpoints
│   ├── virtnbdbackup.0.xml
│   ├── virtnbdbackup.1.xml
├── sda.full.data
├── sda.inc.virtnbdbackup.1.data
├── vm1.cpt
├── vmconfig.virtnbdbackup.0.xml
├── vmconfig.virtnbdbackup.1.xml
```

--------------------------------

### Install advanced virtualization stream on RHEL/CentOS 8.5

Source: https://abbbi.github.io/virtnbdbackup

Use yum to install the advanced virtualization module required for incremental backup support.

```bash
  yum install centos-release-advanced-virtualization
  yum makecache
  yum module install virt
```

--------------------------------

### QEMU Dirty Bitmap Error

Source: https://abbbi.github.io/virtnbdbackup

Example of the error message encountered when attempting to use dirty bitmaps with incompatible qcow2 v2 files.

```text
ERROR [..] internal error: unable to execute QEMU command dirty bitmaps in qcow2 v2 files
```

--------------------------------

### Open Firewall Port for NBD

Source: https://abbbi.github.io/virtnbdbackup

Ensure the NBD port (10809/tcp) is open on the firewall for remote backup functionality in OVIRT-based setups.

```bash
firewall-cmd --zone=public --add-port=10809/tcp
```

--------------------------------

### Ovirt/RHEV Remote Backup via SSH

Source: https://abbbi.github.io/virtnbdbackup

Perform backups remotely on OVIRT-based setups using SSH. Ensure public key authentication is set up and specify connection details including password and user.

```bash
virtnbdbackup -U qemu+ssh://root@hv-node/session -d vm -o /backup --password password --user root --ssh-user root
```

--------------------------------

### Create and Boot Overlay Image

Source: https://abbbi.github.io/virtnbdbackup

Create a bootable overlay image using `qemu-img` from a mapped block device, then boot the virtual machine with it.

```bash
qemu-img create -b /dev/nbd0 -f qcow2 bootme.qcow2
qemu-system-x86_64 -enable-kvm -m 2000 -hda bootme.qcow2
```

--------------------------------

### Create QCOW metadata image

Source: https://abbbi.github.io/virtnbdbackup

Initialize a QCOW2 image with a data-file setting to serve as a metadata container for a RAW device.

```bash
 # point the data-file to a temporary file, as create will overwrite whatever it finds here
 qemu-img create -f qcow2 /tmp/metadata.qcow2 -o data_file=/tmp/TEMPFILE,data_file_raw=true ..
 rm -f /tmp/TEMPFILE
```

--------------------------------

### Configure Libvirt disk for data-file

Source: https://abbbi.github.io/virtnbdbackup

XML configuration snippet for a virtual machine disk using a QCOW2 metadata file with a RAW data-file backend.

```xml
     <disk type='file' device='disk'>
      <driver name='qemu' type='qcow2' cache='none' io='native' discard='unmap'/>
      <source file='/tmp/metadata.qcow2'>
        <dataStore type='file'>
          <format type='raw'/>
          <source file='/your/original/volume.raw'/>
        </dataStore>
      </source>
      <target dev='vda' bus='virtio'/>
    </disk>
```

--------------------------------

### Run virtnbdbackup via Docker

Source: https://abbbi.github.io/virtnbdbackup

Execute the utility using the official Docker image from the GitHub Container Registry.

```bash
 docker run -it ghcr.io/abbbi/virtnbdbackup:master virtnbdbackup
```

--------------------------------

### Rotating Backups with virtnbdbackup

Source: https://abbbi.github.io/virtnbdbackup

Use 'auto' mode for monthly rotation and retention. The first backup is full, subsequent ones are incremental if a full backup exists.

```bash
virtnbdbackup -d vm1 -l auto -o /tmp/2022-06 -> creates full backup
virtnbdbackup -d vm1 -l auto -o /tmp/2022-06 -> creates inc backup
virtnbdbackup -d vm1 -l auto -o /tmp/2022-06 -> creates inc backup
virtnbdbackup -d vm1 -l auto -o /tmp/2022-07 -> creates full backup
virtnbdbackup -d vm1 -l auto -o /tmp/2022-07 -> creates inc backup
```

--------------------------------

### Verify disk image bitmaps

Source: https://abbbi.github.io/virtnbdbackup

Shut down the VM and use qemu-img to inspect the metadata of the disk image for existing bitmaps.

```bash
virsh destroy vm1       # shutdown vm
virsh domblklist vm1 | grep sda
 sda      /tmp/tmp.Y2PskFFeVv/vm1-sda.qcow2
qemu-img info /tmp/tmp.Y2PskFFeVv/vm1-sda.qcow2
[..]
    bitmaps:
        [0]:
            flags:
                [0]: auto
            name: virtnbdbackup.1
            granularity: 65536
[..]
```

--------------------------------

### Backup VM from Remote Host using QEMU

Source: https://abbbi.github.io/virtnbdbackup

Saves a virtual machine from a remote libvirt host to a local directory. Requires specifying the libvirt URI and SSH user for authentication.

```bash
virtnbdbackup -U qemu+ssh://root@hypervisor/system --ssh-user root -d vm1 -o  /tmp/backupset/vm1
```

--------------------------------

### Perform full and incremental backups

Source: https://abbbi.github.io/virtnbdbackup

Commands to execute full and incremental backups for a specified virtual machine domain.

```bash
virtnbdbackup -d vm1 -l full -o /tmp/backupset/vm1
```

```bash
virtnbdbackup -d vm1 -l inc -o /tmp/backupset/vm1
```

--------------------------------

### Perform a complete restore

Source: https://abbbi.github.io/virtnbdbackup

Restores all disks within a backupset into a usable qcow image.

```bash
virtnbdrestore -i /tmp/backupset/vm1 -o /tmp/restore
```

--------------------------------

### Map Backup Image to Block Device

Source: https://abbbi.github.io/virtnbdbackup

Use `virtnbdmap` to map a backup image to `/dev/nbd0`. Ensure the `nbd` kernel module is loaded. Press CTRL+C to disconnect.

```bash
# modprobe nbd max_partitions=15
# virtnbdmap -f /backupset/vm1/sda.full.data
 [..] INFO virtnbdmap - <module> [MainThread]: Done mapping backup image to [/dev/nbd0]
 [..] INFO virtnbdmap - <module> [MainThread]: Press CTRL+C to disconnect
```

--------------------------------

### Enable Compression with LZ4

Source: https://abbbi.github.io/virtnbdbackup

Enable LZ4 compression for the stream format using the --compress option. Default compression level is 2, but can be increased up to 16. virtnbdrestore automatically detects and decompresses compressed streams.

```bash
--compress
--compress=16
```

--------------------------------

### Configure AppArmor for virtnbdbackup Socket Permissions

Source: https://abbbi.github.io/virtnbdbackup

If backups fail with 'Permission denied' when creating a socket file, an active AppArmor profile might be the cause. Add rules to AppArmor configuration files to allow virtnbdbackup to create its socket.

```bash
/var/tmp/virtnbdbackup.* rw,
/var/tmp/backup.* rw,
```

```bash
sudo mkdir -p /etc/apparmor.d/abstractions/libvirt-qemu.d
cat <<EOF | sudo tee /etc/apparmor.d/abstractions/libvirt-qemu.d/virtnbdbackup
/var/tmp/virtnbdbackup.* rw,
/var/tmp/backup.* rw,
EOF
sudo service apparmor reload
```

--------------------------------

### Include Specific Disks for Backup

Source: https://abbbi.github.io/virtnbdbackup

Use the --include or -i option to specify only certain disks for the backup.

```bash
virtnbdbackup -d vm1 -l full -o /tmp/backupset/vm1 -i sdf
```

--------------------------------

### Libvirt Authentication with Authfile

Source: https://abbbi.github.io/virtnbdbackup

Authenticate against libvirtd using an authentication file, similar to `virsh -c` option. This is useful for specifying credentials securely.

```bash
-U qemu:///system?authfile=/etc/virsh_auth.conf ..
```

--------------------------------

### List libvirt checkpoints

Source: https://abbbi.github.io/virtnbdbackup

Use this command to identify which checkpoints libvirt currently tracks for a specific domain.

```bash
virsh checkpoint-list <domain>
```

--------------------------------

### Perform Full Backup and Pipe to Remote Host

Source: https://abbbi.github.io/virtnbdbackup

Executes a full backup of a VM and pipes the uncompressed zip archive to a remote host. Checkpoint files are created locally and must be managed for incremental backups.

```bash
# mkdir backup-weekly; cd backup-weekly
# virtnbdbackup -d vm1 -l full -o - | ssh root@remotehost 'cat > backup-full.zip'
# [..]
# INFO outputhelper - __init__: Writing zip file stream to stdout
# [..]
# INFO virtnbdbackup - main: Finished
# INFO virtnbdbackup - main: Adding vm config to zipfile
# [..]
```

--------------------------------

### Convert QCOW image to compatible version

Source: https://abbbi.github.io/virtnbdbackup

Use this command to upgrade older QCOW images to version 1.1, which is required for dirty bitmap support in incremental backups.

```bash
qemu-img convert -O qcow2 -o compat=1.1 disk-old.qcow2 disk.qcow2
```

--------------------------------

### Map Point-in-Time Recovery Image

Source: https://abbbi.github.io/virtnbdbackup

Create a point-in-time recovery image by providing a sequence of full and incremental backups to `virtnbdmap`. Incremental backups are replayed on the fly.

```bash
virtnbdmap -f /backupset/vm1/sda.full.data,/backupset/vm1/sda.inc.virtnbdbackup.1.data,/backupset/vm1/sda.inc.virtnbdbackup.2.data
[..]
[..] INFO virtnbdmap - main [MainThread]: Need to replay incremental backups
[..] INFO virtnbdmap - main [MainThread]: Replaying offset 420 from /backup/sda.inc.virtnbdbackup.1.data
[..] INFO virtnbdmap - main [MainThread]: Replaying offset 131534 from /backup/sda.inc.virtnbdbackup.1.data
[..]
[..] INFO virtnbdmap - main [MainThread]: Replaying offset 33534 from /backup/sda.inc.virtnbdbackup.2.data
[..] INFO virtnbdmap - <module> [MainThread]: Done mapping backup image to [/dev/nbd0]
[..] INFO virtnbdmap - <module> [MainThread]: Press CTRL+C to disconnect
[..]
```

--------------------------------

### Dump Backup Information using VirtNBDRestore

Source: https://abbbi.github.io/virtnbdbackup

Dumps the metadata information of an existing backup saveset. This includes details like checkpoint name, data size, date, and disk information.

```bash
virtnbdrestore -i /tmp/backupset/vm1 -o dump
INFO:root:Dumping saveset meta information
{'checkpointName': 'virtnbdbackup',
 'dataSize': 704643072,
 'date': '2020-11-15T20:50:36.448938',
 'diskName': 'sda',
 'incremental': False,
 'parentCheckpoint': False,
 'streamVersion': 1,
 'virtualSize': 32212254720}
[..]
```

--------------------------------

### Ovirt/RHEV Local Authentication

Source: https://abbbi.github.io/virtnbdbackup

For Ovirt/RHEV/OLVM environments, use the `-U` parameter with a specific authentication file path to connect to the libvirt daemon when running virtnbdbackup locally on the hypervisor.

```bash
virtnbdbackup -U qemu:///system?authfile=/etc/ovirt-hosted-engine/virsh_auth.conf -d vm1 -o /tmp/backupset/vm1
```

--------------------------------

### Perform Incremental Backup and Pipe to Remote Host

Source: https://abbbi.github.io/virtnbdbackup

Performs an incremental backup of a VM and pipes the data to a remote host. This command must be run from the directory containing the checkpoint files from the full backup.

```bash
# cd backup-weekly
# virtnbdbackup -d vm1 -l inc -o - | ssh root@remotehost 'cat > backup-inc1.zip'
[..]
```

--------------------------------

### Access Mapped Backup Image

Source: https://abbbi.github.io/virtnbdbackup

After mapping a backup image with `virtnbdmap`, you can inspect it using standard disk utilities like `fdisk`.

```bash
fdisk -l /dev/nbd0
Disk /dev/nbd0: 2 GiB, 2147483648 bytes, 4194304 sectors
```

--------------------------------

### Restore with modified configuration

Source: https://abbbi.github.io/virtnbdbackup

Adjusts the virtual machine configuration automatically during the restore process.

```bash
virtnbdrestore -c -i /tmp/backupset/vm1 -o /tmp/restore
[..]
[..] INFO virtnbdrestore - restoreConfig [MainThread]: Adjusted config placed in: [/tmp/restore/vmconfig.virtnbdbackup.0.xml]
[..] INFO virtnbdrestore - restoreConfig [MainThread]: Use 'virsh define /tmp/restore/vmconfig.virtnbdbackup.0.xml' to define VM
```

--------------------------------

### Enable incremental backup in libvirt domain configuration

Source: https://abbbi.github.io/virtnbdbackup

Add the incremental-backup capability to the domain XML configuration using virsh edit.

```xml
  <domain type='kvm' id='1' xmlns:qemu='http://libvirt.org/schemas/domain/qemu/1.0'>
  [..]
  <qemu:capabilities>
    <qemu:add capability='incremental-backup'/>
  </qemu:capabilities>
  [..]
  </domain>
```

--------------------------------

### Restore to a remote host

Source: https://abbbi.github.io/virtnbdbackup

Restores a virtual machine to a remote hypervisor and registers it.

```bash
virtnbdrestore -U qemu+ssh://root@hypervisor/system --ssh-user root -cD -i /tmp/backupset/vm1 -o /remote/target
```

--------------------------------

### Enable NBD Debugging

Source: https://abbbi.github.io/virtnbdbackup

Set the LIBNBD_DEBUG environment variable to enable detailed NBD protocol logging during backup operations.

```bash
export LIBNBD_DEBUG=1
virtnbdbackup [..] --verbose
```

--------------------------------

### Backup Threshold for Incremental/Differential Backups

Source: https://abbbi.github.io/virtnbdbackup

Use the --threshold option to set a minimum data change threshold (in bytes) for executing an incremental or differential backup on an active virtual machine. The backup is skipped if the changed data amount is below the threshold.

```bash
virtnbdbackup -d vm1 -l inc -o /tmp/backupset/vm1 --threshold 3311264
```

```text
[..]
[..] INFO virtnbdbackup - handleCheckpoints [MainThread]: Using checkpoint name: [virtnbdbackup.1].
[..] ]virtnbdbackup - main [MainThread]: Backup size [3211264] does not meet required threshold [3311264], skipping backup.
```

--------------------------------

### Inspect checkpoint XML

Source: https://abbbi.github.io/virtnbdbackup

Examine the XML configuration of a checkpoint to see which disks are associated with specific bitmaps.

```bash
 virsh checkpoint-dumpxml vm1 virtnbdbackup.0 | grep "<disk.*checkpoint="
```

--------------------------------

### Unzip Backup Data for Restore

Source: https://abbbi.github.io/virtnbdbackup

Unzips full and incremental backup archives into a specified directory for restoring virtual machine images.

```bash
# unzip -o -d restoredata backup-full.zip
# unzip -o -d restoredata backup-inc1.zip
```

--------------------------------

### Estimate Incremental Backup Size

Source: https://abbbi.github.io/virtnbdbackup

Use the -p option to estimate the data size for an incremental or differential backup by querying virtual machine checkpoint information. Note that older libvirt versions might not support this feature.

```bash
virtnbdbackup -d vm1 -l inc -o /tmp/backupset/vm1 -p
```

```text
[..]
[..] INFO virtnbdbackup - handleCheckpoints [MainThread]: Using checkpoint name: [virtnbdbackup.1].
[..] INFO virtnbdbackup - main [MainThread]: Estimated checkpoint backup size: [24248320] Bytes
```

--------------------------------

### Forcefully Kill Active Block Jobs with virtnbdbackup

Source: https://abbbi.github.io/virtnbdbackup

Use the -k option with virtnbdbackup to forcibly kill any running active block jobs for a domain. Use with caution and check active operations with `virsh domjobinfo` first.

```bash
virtnbdbackup  -d vm2 -l copy -k  -o -
[..]
  INFO virtnbdbackup - main: Stopping domain jobs
```

--------------------------------

### Freeze specific mountpoints

Source: https://abbbi.github.io/virtnbdbackup

Command to perform an incremental backup while freezing only specific filesystem mountpoints.

```bash
virtnbdbackup -d vm1 -l inc -o /tmp/backupset/vm1 -F /mnt,/var
```

--------------------------------

### Redefine Missing Checkpoints with Shared Directory

Source: https://abbbi.github.io/virtnbdbackup

When a VM is relocated and loses checkpoint information, passing the `--checkpointdir` with the shared directory allows virtnbdbackup to redefine missing checkpoints and complete a full backup successfully.

```bash
virtnbdbackup -d vm1 -l full -o /tmp/backup_hostb --checkpointdir /mnt/shared/vm1
```

--------------------------------

### Disable Sparse Detection in virtnbdbackup

Source: https://abbbi.github.io/virtnbdbackup

By default, virtnbdbackup detects trimmed blocks during incremental backups. Use the `--no-sparse-detection` option to disable this behavior if it causes issues with backup sizes.

```bash
--no-sparse-detection
```

--------------------------------

### Perform point in time recovery

Source: https://abbbi.github.io/virtnbdbackup

Restores to a specific checkpoint or using a specific sequence of data files.

```bash
virtnbdrestore -i /tmp/backupset/vm1 -o /tmp/restore --until virtnbdbackup.2
```

```bash
virtnbdrestore -i /tmp/backupset/vm1 -o /tmp/restore --sequence vdb.full.data,vdb.inc.virtnbdbackup.1.data
```

--------------------------------

### Configure Backup Worker Threads

Source: https://abbbi.github.io/virtnbdbackup

Control the number of threads used for backup with the --worker option. For standard output ('-') as target, the worker count is limited to 1 to ensure a valid Zip file format.

```bash
virtnbdbackup --worker <number_of_threads>
```

--------------------------------

### Amend QCOW metadata image

Source: https://abbbi.github.io/virtnbdbackup

Update the data-file reference of an existing QCOW2 metadata image to point to the target RAW device.

```bash
 qemu-img amend /tmp/metadata.qcow2 -o data_file=/your/original/volume.raw,data_file_raw=true
```

--------------------------------

### Restore a specific disk

Source: https://abbbi.github.io/virtnbdbackup

Restores only a single disk by matching the target name.

```bash
virtnbdrestore -i /tmp/backupset/vm1 -o /tmp/restore -d sda
```

--------------------------------

### Exclude Disks from Backup

Source: https://abbbi.github.io/virtnbdbackup

Use the -x option to exclude disks by their target device name. Special devices like cdrom/floppy are excluded by default.

```bash
virtnbdbackup -d vm1 -l full -o /tmp/backupset/vm1 -x sda
```

--------------------------------

### Verify backup integrity

Source: https://abbbi.github.io/virtnbdbackup

Checks the integrity of backup data files without performing a full restore.

```bash
virtnbdrestore -i /tmp/backup/vm1 -o verify
[..] INFO lib common - printVersion [MainThread]: Version: 1.9.39 Arguments: ./virtnbdrestore -i /tmp/backup/vm1 -o verify
[..] INFO root virtnbdrestore - verify [MainThread]: Computing checksum for: /tmp/backup/vm1/sda.full.data
[..] INFO root virtnbdrestore - verify [MainThread]: Checksum result: 541406837
[..] INFO root virtnbdrestore - verify [MainThread]: Comparing checksum with stored information
[..] INFO root virtnbdrestore - verify [MainThread]: OK
```

--------------------------------

### Store Checkpoints in Shared Directory

Source: https://abbbi.github.io/virtnbdbackup

Use `--checkpointdir` to store VM checkpoint information in a shared directory accessible by multiple cluster nodes. This ensures checkpoints are not lost when a VM is relocated.

```bash
virtnbdbackup -d vm1 -l full -o /tmp/backup_hosta --checkpointdir /mnt/shared/vm1
```

--------------------------------

### Delete libvirt checkpoints

Source: https://abbbi.github.io/virtnbdbackup

Remove a specific checkpoint from libvirt metadata to resolve inconsistencies or broken chains.

```bash
 virsh checkpoint-delete <domain> --checkpointname <checkpoint_name> --metadata
```

--------------------------------

### Remove dangling bitmaps

Source: https://abbbi.github.io/virtnbdbackup

Manually remove an inconsistent or dangling bitmap from a qcow2 image file.

```bash
  qemu-img bitmap /tmp/tmp.Y2PskFFeVv/vm1-sda.qcow2 --remove virtnbdbackup.1
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.