### Start local full backup

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Initiate a full backup of a virtual domain named 'vm1'. The backup data will be saved to the specified output directory '/tmp/backupset/vm1'. This command is used for the initial backup or when a full backup is required.

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

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

### Install virtnbdbackup using pip

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Clone the repository and install the virtnbdbackup package using pip. Ensure you do not install the conflicting 'nbd' package from PyPI; instead, install the required python3-libnbd package separately.

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

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

### Start local incremental backup

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Perform an incremental backup for domain 'vm1'. This command backs up only the blocks that have changed since the last full backup. The same output directory is used, allowing subsequent incremental backups to be stored alongside the full backup.

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

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

### Launch Interactive Container Session

Source: https://github.com/abbbi/virtnbdbackup/blob/master/docker/README.md

Starts a volatile container session with necessary bind mounts for manual backups, restores, or troubleshooting.

```bash
docker run -it --rm \
-v /run:/run \
-v /var/tmp:/var/tmp \
-v /etc/libvirt/qemu/nvram:/etc/libvirt/qemu/nvram \
-v /usr/share/OVMF:/usr/share/OVMF \
-v /mnt/backups:/backups \
-v /<path-to-virtual-disks>:/<path-to-virtual-disks> \
ghcr.io/abbbi/virtnbdbackup \
bash
```

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

### Install libvirt from Advanced Virtualization Stream (RHEL/CentOS <= 8.5)

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Install libvirt from the advanced virtualization stream for RHEL/CentOS versions 8.5 and older to ensure support for incremental backup features. This involves enabling the stream, updating the package cache, and installing the virt module.

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

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

### Start Backup Job Only (Debug)

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Starts a backup job without data transfer for debugging purposes.

```bash
# Start backup job only (for debugging, no data transfer)
virtnbdbackup -d webvm -l full -o /backup/webvm -s
```

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

### Open firewall port for NBD backup

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Ensure the NBD port (10809/tcp) is open on the firewall when performing backups on OVIRT-based setups, especially when using remote backup functionality.

```bash
root@hv-node~# firewall-cmd --zone=public --add-port=10809/tcp
```

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

### Instant Boot VM from Backup

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Creates an overlay image and boots a virtual machine directly from a backup using virtnbdmap for instant recovery.

```bash
# Map the backup image
virtnbdmap -f /backup/webvm/sda.full.data &

# Create overlay image for boot
qemu-img create -b /dev/nbd0 -f qcow2 bootme.qcow2

# Boot the virtual machine
qemu-system-x86_64 -enable-kvm -m 2048 -hda bootme.qcow2

# After done, stop virtnbdmap with CTRL+C
```

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

### Create Overlay Image and Boot VM

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Create a qcow2 overlay image based on the mapped block device and boot a virtual machine using this overlay. This allows for immediate booting from the restored data.

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

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

### Libvirt Authentication (QEMU Session)

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Connects to a local QEMU session for libvirt authentication, suitable for non-root users.

```bash
# Connect to local QEMU session (non-root user)
virtnbdbackup -U qemu:///session -d webvm -l full -o /backup/webvm
```

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

### Create QCOW image with data-file setting

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Use this command to create a QCOW image that utilizes a data-file for storing virtual machine data. Ensure the data_file points to a temporary file initially, as 'create' will overwrite it. The data_file_raw=true option is crucial for RAW backend devices.

```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 VM disk for QCOW with data-file

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Modify your virtual machine's disk configuration to use the QCOW image as the primary disk. The <source> element should point to the QCOW image, and a nested <dataStore> element specifies the RAW backend device.

```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>
```

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

### Execute All VM Tests with Make

Source: https://github.com/abbbi/virtnbdbackup/blob/master/t/README.txt

To execute all defined virtual machine tests within the project, use the 'make all' command. This command orchestrates the execution of all individual VM tests.

```bash
make all
```

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

### Enable Incremental Backup in VM Config (libvirt <= 7.6.0)

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Modify the virtual machine's XML configuration to enable the incremental backup capability for libvirt versions 7.6.0 and older. This requires adding a qemu capability. Power cycle the VM after making changes.

```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>
```

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

### Run Docker Image

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Execute the virtnbdbackup application from a Docker container. Ensure the Docker daemon is running and you have network access.

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

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

### Execute Complete Restore

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Restores virtual machine disks from a backup set with options for configuration adjustment and image provisioning.

```bash
# Complete restore of all disks
virtnbdrestore -i /backup/webvm -o /restore/webvm

# Restore with adjusted VM config and auto-define in libvirt
virtnbdrestore -cD -i /backup/webvm -o /restore/webvm

# Restore with custom VM name
virtnbdrestore -cD --name restored-webvm -i /backup/webvm -o /restore/webvm

# Restore with preallocated (thick provisioned) images
virtnbdrestore -A -i /backup/webvm -o /restore/webvm

# Restore with compression driver (for originally compressed images)
virtnbdrestore --compress -i /backup/webvm -o /restore/webvm
```

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

### Convert Disk Image to QCOW2

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Convert an older disk image format to qcow2 using qemu-img. This is necessary for incremental backups with older libvirt/qemu versions.

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

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

### Perform Application Consistent Backups

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Freezes filesystems via QEMU guest agent or pauses the VM to ensure data consistency during the backup process.

```bash
# Standard backup with automatic filesystem freeze (requires qemu-guest-agent)
virtnbdbackup -d webvm -l full -o /backup/webvm

# Freeze only specific mountpoints
virtnbdbackup -d webvm -l full -F /var,/data -o /backup/webvm

# Pause VM during backup job start (alternative when guest agent unavailable)
virtnbdbackup -d webvm -l full --pause -o /backup/webvm
```

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

### Backup VM from Remote Host using QEMU

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

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

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

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

### Execute Specific VM Test with Make

Source: https://github.com/abbbi/virtnbdbackup/blob/master/t/README.txt

To run tests for a particular virtual machine, use the 'make' command followed by the VM name and '.test'. Ensure your environment is set up for BATS testing.

```bash
make vm1.test
```

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

### List qcow2 image bitmaps

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Shut down the VM and inspect the qcow2 file to identify existing bitmaps within the disk metadata.

```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
[..]
```

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

### Libvirt Authentication (Auth File)

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Connects to a libvirt daemon using an authentication file, typically for OVIRT/RHEV environments.

```bash
# Using authentication file (OVIRT/RHEV)
virtnbdbackup -U 'qemu:///system?authfile=/etc/ovirt-hosted-engine/virsh_auth.conf' \
    -d webvm \
    -l full \
    -o /backup/webvm
```

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

### Perform a complete restore

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Restores all disks within a backupset into usable qcow images in the specified output directory.

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

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

### Authenticate with Ovirt/RHEV hypervisor

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

When using virtnbdbackup with Ovirt/RHEV, use the `-U` parameter to specify an authentication file if running locally on the hypervisor. This is necessary due to restricted access to the libvirt daemon.

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

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

### Specify Connection URI with Auth File

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Use this option to specify an arbitrary connection URI to libvirt, including an authentication file for credentials.

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

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

### Including Specific Disks in Backup

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Use the --include or -i option to specify only certain disks to be backed up.

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

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

### Perform Full VM Backups

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Executes a complete backup of a virtual machine. Compression can be enabled using the -z flag with an optional level from 1 to 16.

```bash
# Full backup of domain 'webvm' with all attached disks
virtnbdbackup -d webvm -l full -o /backup/webvm

# Example output structure:
# /backup/webvm/
# ├── backup.full.01152024120000.log
# ├── checkpoints/
# │   └── virtnbdbackup.0.xml
# ├── sda.full.data
# ├── webvm.cpt
# └── vmconfig.virtnbdbackup.0.xml

# Full backup with compression enabled (lz4)
virtnbdbackup -d webvm -l full -z -o /backup/webvm

# Full backup with custom compression level (1-16)
virtnbdbackup -d webvm -l full -z 8 -o /backup/webvm
```

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

### Compress Backup Images

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Use the --compress option to compress backup images to save storage space, especially when thin-provisioned backups are larger than original qcow images.

```bash
 --compress
```

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

### Perform Incremental Backup and Pipe to Remote Host

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Creates an incremental backup of a VM and pipes the uncompressed zip archive to a remote host via SSH. Must be run from the directory containing checkpoint files.

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

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

### Run Virtnbdbackup Docker Container for VM Backup

Source: https://github.com/abbbi/virtnbdbackup/blob/master/docker/README.md

This command runs the virtnbdbackup Docker container to perform a full or incremental backup of a specified virtual machine. Ensure all necessary bind mounts for libvirt, temporary directories, OVMF files, and backup storage are correctly configured on the host system.

```bash
docker run --rm \
-v /run:/run \
-v /var/tmp:/var/tmp \
-v /etc/libvirt/qemu/nvram:/etc/libvirt/qemu/nvram \
-v /usr/share/OVMF:/usr/share/OVMF \
-v /<path-to-backups>:/backups \
ghcr.io/abbbi/virtnbdbackup:master \
virtnbdbackup -d <domain> -l auto -o /backups/<domain>
```

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

### Perform Full Backup and Pipe to Remote Host

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Creates a full backup of a VM and pipes the uncompressed zip archive to a remote host via SSH. Checkpoint files are created locally 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
# [..]
```

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

### Enable NBD Debugging and Verbose Output

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Export the LIBNBD_DEBUG environment variable and use the --verbose option for detailed debugging output during backup operations.

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

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

### Dump Backup Information using virtnbdrestore

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Dumps saveset meta information from an existing backup. Useful for inspecting backup details like 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}
[..]
```

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

### Stream Backups to Standard Output

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Streams backup data as a zip archive to stdout, allowing for piping to files or remote systems.

```bash
# Backup to stdout and save as zip file
virtnbdbackup -d webvm -l full -o - > /backup/webvm-full.zip

# Pipe backup directly to remote host
virtnbdbackup -d webvm -l full -o - | ssh user@remotehost 'cat > backup-full.zip'
```

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

### List Disk Information for Mapped Device

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

After mapping a backup image to a block device (e.g., /dev/nbd0), you can use standard tools like fdisk to inspect its details.

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

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

### List libvirt checkpoints

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

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

```bash
virsh checkpoint-list <domain>
 Name              Creation Time
 ----------------------------------------------
 virtnbdbackup.0   2024-08-01 20:45:44 +0200
```

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

### Perform Incremental VM Backups

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Backs up only changed blocks since the last operation. Requires an existing full backup in the target directory.

```bash
# Incremental backup (requires existing full backup in target directory)
virtnbdbackup -d webvm -l inc -o /backup/webvm

# Example output adds to existing backup:
# /backup/webvm/
# ├── sda.full.data
# ├── sda.inc.virtnbdbackup.1.data    # New incremental
# ├── checkpoints/
# │   ├── virtnbdbackup.0.xml
# │   └── virtnbdbackup.1.xml         # New checkpoint
# └── vmconfig.virtnbdbackup.1.xml

# Multiple incremental backups create a chain
virtnbdbackup -d webvm -l inc -o /backup/webvm  # Creates virtnbdbackup.2
virtnbdbackup -d webvm -l inc -o /backup/webvm  # Creates virtnbdbackup.3
```

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

### Handle missing checkpoints on relocated VM

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

When a VM is relocated to a new host and loses checkpoint information, a backup attempt may fail with 'Bitmap already exists'. Passing the `--checkpointdir` from the previous host allows virtnbdbackup to redefine missing checkpoints and succeed.

```bash
virtnbdbackup -d vm1 -l full -o /tmp/backup_hostb
[..]
unable to execute QEMU command 'transaction': Bitmap already exists: virtnbdbackup.0
```

```bash
virtnbdbackup -d vm1 -l full -o /tmp/backup_hostb --checkpointdir /mnt/shared/vm1
[..]
redefineCheckpoints: Redefine missing checkpoint virtnbdbackup.0
[..]
```

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

### Configure AppArmor for virtnbdbackup

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

If backups fail with 'Permission denied' when creating the socket file, AppArmor might be preventing it. Disable AppArmor temporarily with `aa-teardown` or add specific rules to AppArmor configuration files.

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

```bash
/etc/apparmor.d/usr.lib.libvirt.virt-aa-helper
/etc/apparmor.d/local/abstractions/libvirt-qemu
/etc/apparmor.d/local/usr.sbin.libvirtd
```

```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
```

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

### Create Point-in-Time Recovery Image

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Map a sequence of full and incremental backups to create a point-in-time recovery image. Changes from incremental backups are replayed on the fly. The original image remains untouched due to nbdkit's copy-on-write filter. Press CTRL+C to disconnect.

```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
[..]
```

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

### Amend QCOW image to point to RAW device

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

After creating the metadata QCOW image, use 'qemu-img amend' to update the data_file setting to your actual RAW device. This links the QCOW image's metadata to the persistent storage of your virtual machine's data.

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

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

### Perform remote backup with SSH authentication

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

This command demonstrates performing a backup using remote functionality via SSH. Ensure public key authentication is set up and specify necessary parameters like password and user if required.

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

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

### Map Backup to Block Device

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Maps backup images to NBD block devices, allowing for file-level access or instant boot scenarios.

```bash
# Load nbd kernel module first
modprobe nbd max_partitions=15

# Map full backup to /dev/nbd0
virtnbdmap -f /backup/webvm/sda.full.data

# Map to specific device
virtnbdmap -f /backup/webvm/sda.full.data -d /dev/nbd2

# Map with incremental replay for point-in-time access
virtnbdmap -f /backup/webvm/sda.full.data,/backup/webvm/sda.inc.virtnbdbackup.1.data

# Mount and access files (while virtnbdmap is running)
# In another terminal:
mount /dev/nbd0p1 /mnt/restore
ls /mnt/restore
umount /mnt/restore
```

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

### Use Auto Backup Mode

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Automatically selects between full and incremental modes based on the contents of the target directory.

```bash
# Auto mode - creates full if empty, incremental if full exists
virtnbdbackup -d webvm -l auto -o /backup/2024-01

# Example monthly rotation:
virtnbdbackup -d webvm -l auto -o /backup/2024-01  # Creates full
virtnbdbackup -d webvm -l auto -o /backup/2024-01  # Creates incremental
virtnbdbackup -d webvm -l auto -o /backup/2024-02  # New month = new full
```

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

### Map Backup Image to Network Block Device

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Use virtnbdmap to map a backup image to a network block device. Ensure nbd kernel module is loaded and execute with root privileges. 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 Verbose Debug Output

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Enables verbose logging for troubleshooting backup issues.

```bash
# Enable verbose debug output
virtnbdbackup -d webvm -l full -o /backup/webvm -v
```

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

### Restore VM Backup to Existing VM

Source: https://github.com/abbbi/virtnbdbackup/blob/master/docker/README.md

Executes a full restoration by moving existing disk images to a backup folder before restoring from the backup source. Ensure bind mounts for virtual disks and backup locations are correctly configured.

```bash
docker run --rm \
-v /run:/run \
-v /var/tmp:/var/tmp \
-v /etc/libvirt/qemu/nvram:/etc/libvirt/qemu/nvram \
-v /usr/share/OVMF:/usr/share/OVMF \
-v /mnt/backups:/backups \
-v /<path-to-virtual-disks>:/<path-to-virtual-disks> \
ghcr.io/abbbi/virtnbdbackup:master \
bash -c \
"mkdir -p /<path-to-virtual-disks>/<domain>.old && \
mv /<path-to-virtual-disks>/<domain>/* /<path-to-virtual-disks>/<domain>.old/ && \
virtnbdrestore -i /backups/<domain> -o /<path-to-virtual-disks>/<domain>"
```

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

### Libvirt Authentication (SASL)

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Uses SASL authentication with username and password to connect to a libvirt daemon over TCP.

```bash
# SASL authentication with username/password
virtnbdbackup -U qemu+tcp://hostname/system \
    --user admin \
    --password secret \
    -d webvm \
    -l full \
    -o /backup/webvm
```

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

### Inspect checkpoint disk configuration

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Verify which disks are included in a specific checkpoint and their associated bitmap status.

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

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

### Unzip Backup Data for Restore

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

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

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

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

### Add bitmap to qcow2 image

Source: https://github.com/abbbi/virtnbdbackup/blob/master/t/vm5/README.txt

Use this command to manually add a bitmap to a qcow2 image file for use with virtnbdbackup.

```bash
qemu-img bitmap --add vm5-sda.qcow2 virtnbdbackup.0
```

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

### Backup Offline Virtual Machines

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Handles VMs that are powered off using copy mode or by temporarily pausing the domain.

```bash
# Copy backup of offline VM (no checkpoint created)
virtnbdbackup -d webvm -l copy -o /backup/webvm

# Start offline VM in paused state for full backup capability
virtnbdbackup -d webvm -l full -S -o /backup/webvm

# Auto mode with start-domain flag (works for any VM state)
virtnbdbackup -d webvm -l auto -S -o /backup/webvm
```

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

### Enabling LZ4 Compression

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Enable LZ4 compression for the stream format using the --compress option. Compression level 2 is default, higher levels like 16 can be specified. Decompression is automatic during restore.

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

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

### Estimating Incremental Backup Size

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Use the -p option to estimate the size of an incremental or differential backup by querying virtual machine checkpoint information. Ensure your libvirt version supports the necessary flags.

```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
```

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

### Estimate Backup Size and Thresholding

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Queries the estimated size of a backup before execution or triggers backups based on data change thresholds.

```bash
# Print estimated checkpoint backup size without running backup
virtnbdbackup -d webvm -l inc -o /backup/webvm -p

# Example output:
# INFO virtnbdbackup - handleCheckpoints: Using checkpoint name: [virtnbdbackup.1].
# INFO virtnbdbackup - main: Estimated checkpoint backup size: [24248320] Bytes

# Execute backup only if changed data exceeds threshold (bytes)
virtnbdbackup -d webvm -l inc -o /backup/webvm --threshold 1073741824  # 1GB
```

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

### Backup Threshold for Incremental/Differential Backups

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

The --threshold option allows specifying a minimum amount of changed data (in bytes) required to execute an incremental or differential backup when the VM is active. Backups are skipped if the threshold is not met.

```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.
```

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

### Forcefully Kill Active Block Jobs with virtnbdbackup

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Use the -k option to forcibly kill any running active block jobs for a domain when backups fail due to lock timeouts. Use with caution and consider checking active operations with `virsh domjobinfo` first.

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

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

### Rotating Backups with Auto Mode

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Use 'auto' mode for monthly rotation and retention. The first backup is full, subsequent ones are incremental if the target folder 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
```

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

### Enable NBD Protocol Debugging

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Enables NBD protocol debugging by setting the LIBNBD_DEBUG environment variable.

```bash
# Enable NBD protocol debugging
export LIBNBD_DEBUG=1
virtnbdbackup -d webvm -l full -o /backup/webvm -v
```

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

### Perform Point-in-Time Restore

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

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

```bash
# Restore only up to checkpoint virtnbdbackup.2
virtnbdrestore -i /backup/webvm -o /restore/webvm --until virtnbdbackup.2

# Restore specific sequence of backup files
virtnbdrestore -i /backup/webvm -o /restore/webvm \
    --sequence sda.full.data,sda.inc.virtnbdbackup.1.data
```

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

### Perform Incremental Backup to Stdout

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Streams an incremental backup directly to stdout, useful for piping to remote storage via SSH.

```bash
cd /backup/checkpoints
virtnbdbackup -d webvm -l inc -o - | ssh user@remotehost 'cat > backup-inc1.zip'
```

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

### Checkpoint Persistence for Clusters

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Stores checkpoints in a shared directory for transient VMs in cluster environments, ensuring checkpoints survive VM migrations.

```bash
# Backup with persistent checkpoint storage
virtnbdbackup -d webvm -l full -o /backup/webvm \
    -C /shared/checkpoints/webvm

# After VM migration to another host, checkpoints are auto-redefined
virtnbdbackup -d webvm -l inc -o /backup/webvm \
    -C /shared/checkpoints/webvm
```

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

### Create backup with persistent checkpoints

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Use `--checkpointdir` to store checkpoint information in a shared directory, ensuring persistence across hosts in a cluster. This is useful when a VM migrates and the new host loses checkpoint information.

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

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

### Restore to a remote host

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Restores a virtual machine to a remote hypervisor using SSH and automatically registers the VM.

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

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

### Freeze specific mountpoints during backup

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

To ensure filesystem consistency for specific directories during a backup, use the '-F' option with a comma-separated list of mountpoints. This command freezes only the filesystems mounted on '/mnt' and '/var' before proceeding with an incremental backup of 'vm1'.

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

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

### Execute Remote Backups via SSH

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Performs backups from remote libvirt hosts using SSH transport. Supports custom ports, TLS encryption, and specific IP binding.

```bash
# Remote backup using qemu+ssh URI
virtnbdbackup -U qemu+ssh://root@hypervisor/system \
    --ssh-user root \
    -d webvm \
    -l full \
    -o /local/backup/webvm

# Remote backup with custom NBD port (required for concurrent backups)
virtnbdbackup -U qemu+ssh://root@hypervisor/system \
    --ssh-user root \
    -P 10810 \
    -d webvm \
    -l full \
    -o /local/backup/webvm

# Remote backup with TLS encryption for NBD transfer
virtnbdbackup -U qemu+ssh://root@hypervisor/system \
    --ssh-user root \
    --tls \
    -d webvm \
    -l full \
    -o /local/backup/webvm

# Bind NBD service to specific IP for dedicated backup network
virtnbdbackup -U qemu+ssh://root@hypervisor/system \
    --ssh-user root \
    -I 192.168.100.10 \
    -d webvm \
    -l full \
    -o /local/backup/webvm
```

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

### Restore Specific Disk

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Restores an individual disk from a backup set, optionally including configuration adjustments.

```bash
# Restore only disk 'sda'
virtnbdrestore -i /backup/webvm -o /restore/webvm -d sda

# Restore specific disk with config adjustment
virtnbdrestore -c -i /backup/webvm -o /restore/webvm -d sda
```

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

### Send Logs to Syslog

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Configures the tool to send logs to syslog.

```bash
# Send logs to syslog
virtnbdbackup -d webvm -l full -o /backup/webvm -L
```

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

### RAW Disk Backup

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Includes RAW disk images and direct-attached volumes in full backups. Note that RAW disks cannot be included in incremental backups.

```bash
# Include raw disks in full backup
virtnbdbackup -d webvm -l full --raw -o /backup/webvm

# Note: Raw disks cannot be included in incremental backups
# For incremental support with raw volumes (libvirt >= 10.10.0),
# use QCOW2 metadata files with data-file setting
```

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

### Perform Remote Restore

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Restores a virtual machine directly to a remote libvirt host using SSH.

```bash
# Remote restore with VM definition
virtnbdrestore -U qemu+ssh://root@hypervisor/system \
    --ssh-user root \
    -cD \
    -i /local/backup/webvm \
    -o /remote/restore/webvm
```

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

### Concurrent Backup Workers

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Configures multiple worker threads for backing up VMs with multiple disks, enabling parallel disk backup.

```bash
# Use 4 concurrent workers for parallel disk backup
virtnbdbackup -d webvm -l full -w 4 -o /backup/webvm

# Default is one worker per disk attached to VM
```

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

### Disable Sparse Detection in virtnbdbackup

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

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
```

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

### Excluding Disks from Backup

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Use the -x option to exclude specific 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
```

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

### Restore with modified VM configuration

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Adjusts the virtual machine configuration during restore, such as removing UUIDs and updating disk paths.

```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
```

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

### Perform point in time recovery

Source: https://github.com/abbbi/virtnbdbackup/blob/master/README.md

Restores data up 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
```

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

### Map Readonly NBD Device

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Maps a backup image to a read-only NBD device. Requires special mount options for mounting.

```bash
virtnbdmap -f /backup/webvm/sda.full.data -r
# Mount with: mount -o norecovery,ro /dev/nbd0p1 /mnt
```

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

### Verify Backup Integrity

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Checks the integrity of backup data files by computing and comparing checksums.

```bash
# Verify all data files in backup
virtnbdrestore -i /backup/webvm -o verify

# Example output:
# INFO virtnbdrestore - verify: Computing checksum for: /backup/webvm/sda.full.data
# INFO virtnbdrestore - verify: Checksum result: 541406837
# INFO virtnbdrestore - verify: Comparing checksum with stored information
# INFO virtnbdrestore - verify: OK

# Verify with custom buffer size for performance
virtnbdrestore -i /backup/webvm -o verify -B 65536
```

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

### Quiet Mode

Source: https://context7.com/abbbi/virtnbdbackup/llms.txt

Enables quiet mode, logging only to a file.

```bash
# Quiet mode (log to file only)
virtnbdbackup -d webvm -l full -o /backup/webvm --quiet
```