Event-Driven Backup, starting with the Incident API

100% of all Veeam customers have prescriptive Backup Jobs to protect their mission critical workloads. This is done by creating a backup job, adding your resources and selecting a target, schedule and retention setting for this backup job.

These jobs run and hopefully the recovery point objective is met with this schedule.

This is not strictly 100% true as some people are likely using vSphere tags to dynamically protect workloads as well… We find the same labels and tags in cloud-based workloads.

The world is more dynamic so we should make sure if there is a smoke signal of something bad happening then we should trigger a backup just in case.

Veeam Data Platform

Back in the 12.1 release of the Veeam Data Platform there was a little feature called the Incident API. I want to talk about that API in this post, the overall marketing around this feature was really focused on security smoke signals or as the name suggests incidents.

But what if this was based on any event.

Overall release blog - https://www.veeam.com/blog/veeam-incident-application-programming-interface.html

User Guide - https://helpcenter.veeam.com/docs/backup/vsphere/malware_detection_incident_api.html?ver=120

The incident API uses a longstanding feature that Veeam have honed and had for many years called Quick Backup. A quick backup allows you to create an on-demand incremental backup of your VMs.

We must enable the Incident API within Veeam Backup and Replication to start.

Now for the fun stuff...

We should now target our VM(s) that we wish to be targeted when such an event take place, the name is easy to obtain. We then will also need the UUID for that machine. I chose to use govc to gather this UUID, I am sure you have many other ways to get this, PowerCLI? Can you get this from the vCenter interface?

You will need to connect to your server using govc, if you would like to see more detail on how to do this and what else this can be useful for then let me know down below.

The command I used is

govc vm.info -json DevOps-MGMT01 | grep "uuid"

Depending on the VM you are querying you might get a return of 3 UUIDs, the first and last one will match, and this is the one we should use in the next steps. If you have several targeted machines which is possible then rinse and repeat.

Here is the bash script I am using, note that you will need to update your veeam server IP or FQDN, the bash script will prompt you for the username and password or you can rely on environment variables.

#!/bin/bash

# Function to securely read input
read_secure_input() {
  local prompt="$1"
  read -s -p "$prompt" input
  echo "$input"
}

# Prompt for credentials or use environment variables
URL="${VEEAM_API_URL:-https://192.168.169.185:9419/api/oauth2/token}"
USERNAME="${VEEAM_API_USERNAME:-}"
PASSWORD="${VEEAM_API_PASSWORD:-}"

if [ -z "$USERNAME" ]; then
  read -p "Enter username: " USERNAME
fi

if [ -z "$PASSWORD" ]; then
  PASSWORD=$(read_secure_input "Enter password: ")
  echo
fi

# Obtain token
BODY=$(jq -n \
  --arg grant_type "password" \
  --arg username "$USERNAME" \
  --arg password "$PASSWORD" \
  '{grant_type: $grant_type, username: $username, password: $password}')

HEADERS=(
  -H "Content-Type: application/json"
  -H "x-api-version: 1.1-rev1"
)

echo "Obtaining access token..."
RESPONSE=$(curl -s -k -X POST "$URL" -d "$BODY" "${HEADERS[@]}")
TOKEN=$(echo "$RESPONSE" | jq -r .access_token)

if [ -z "$TOKEN" ] || [ "$TOKEN" == "null" ]; then
  echo "Failed to obtain access token. Check credentials and URL."
  exit 1
fi

# Prepare headers with token
AUTH_HEADERS=(
  -H "Content-Type: application/json"
  -H "x-api-version: 1.1-rev1"
  -H "Authorization: Bearer $TOKEN"
)

# Define event data
DETECTION_TIME="$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)"
FQDN="DevOps-MGMT01"
#UUID="423738ed-997d-80d4-328f-f4fd78c887a4"
DETAILS="Event-Driven Backup Demo"
SEVERITY="Infected"
ENGINE="Event-Driven"

EVENT_BODY=$(jq -n \
  --arg detectionTimeUtc "$DETECTION_TIME" \
  --arg fqdn "$FQDN" \
#  --arg uuid "$UUID" \
  --arg details "$DETAILS" \
  --arg severity "$SEVERITY" \
  --arg engine "$ENGINE" \
  '{
    detectionTimeUtc: $detectionTimeUtc,
    machine: {fqdn: $fqdn, uuid: $uuid},
    details: $details,
    severity: $severity,
    engine: $engine
  }')

# Trigger event
EVENT_URL="https://192.168.169.185:9419/api/v1/malwareDetection/events"
echo "Triggering event..."
EVENT_RESPONSE=$(curl -s -k -X POST "$EVENT_URL" -d "$EVENT_BODY" "${AUTH_HEADERS[@]}")

if echo "$EVENT_RESPONSE" | jq . >/dev/null 2>&1; then
  echo "Event triggered successfully:"
  echo "$EVENT_RESPONSE" | jq
else
  echo "Failed to trigger event. Response: $EVENT_RESPONSE"
fi

This approach especially if the environment variables are set will enable this script to be triggered over and over. 

Instead me typing everything up though, its much easier to show you the process I took and then although this is me manually showing you this process this could be triggered by way of an event, our marketing talks about security smoke signals and network detection etc but this could be based on any event that would warrant this action to take place.

That’s all folks, This was a very simple way to look at how to think about event driven architecture when it comes to Backup. We can take this principle and expand on this a lot using the Veeam API to do something based on an event. 

Backup windows are not going away any time soon but I see a requirement where we need to be more dynamic when it comes to protecting and providing resilience to those mission critical workloads.