[PATCH docs 21/21] examples: add example hook script for host backup jobs

[Shannon Sterz <s.sterz@proxmox.com>]

Signed-off-by: Shannon Sterz <s.sterz@proxmox.com>
---
 Makefile                                   |  1 +
 examples/host-backup-example-hookscript.pl | 90 ++++++++++++++++++++++
 2 files changed, 91 insertions(+)
 create mode 100755 examples/host-backup-example-hookscript.pl

diff --git a/Makefile b/Makefile
index db07f2e..13ddb73 100644
--- a/Makefile
+++ b/Makefile
@@ -218,6 +218,7 @@ doc-install: index.html $(WIKI_IMPORTS) $(API_VIEWER_SOURCES) verify-images exam
 	install -dm755 $(DESTDIR)/usr/share/doc/$(DOC_PACKAGE)
 	install -dm755 $(DESTDIR)/usr/share/$(DOC_PACKAGE)/examples/
 	install -m 755 examples/guest-example-hookscript.pl $(DESTDIR)/usr/share/$(DOC_PACKAGE)/examples/
+	install -m 755 examples/host-backup-example-hookscript.pl $(DESTDIR)/usr/share/$(DOC_PACKAGE)/examples/
 	install -m 0644 index.html $(INDEX_INCLUDES) $(DESTDIR)/usr/share/$(DOC_PACKAGE)
 	install -m 0644 $(WIKI_IMPORTS) $(DESTDIR)/usr/share/$(DOC_PACKAGE)
 	# install images
diff --git a/examples/host-backup-example-hookscript.pl b/examples/host-backup-example-hookscript.pl
new file mode 100755
index 0000000..9791814
--- /dev/null
+++ b/examples/host-backup-example-hookscript.pl
@@ -0,0 +1,90 @@
+#!/usr/bin/perl
+
+# Example host backup hook script. Currently these need to be added
+# manually to a host backup job (or as an API parameter to a one off
+# host backup).
+
+use v5.36;
+
+# First argument is the backup phase.
+
+my $phase = shift;
+
+# A payload is provided via `stdin` as JSON encoded. This will only
+# exist for certain stages. Parameters may be added to the payload
+# over time. Make sure a hook script can handle additional fields,
+# for better compatibility.
+
+my @input = <STDIN>;
+my $payload = join('\n', @input);
+
+if ($phase eq 'job-start') {
+
+    # A backup was started. Other than validating the parameters of
+    # the job, nothing has been done yet.
+
+    # This stage has no payload:
+    die "Unknown payload: '$payload'\n" if $payload ne '';
+
+    # If the script returns only a valid JSON string that contains an
+    # object with a single string member called `base-path`, that
+    # string will be used as the base path of the backup. It needs to
+    # point to a directory.
+    #
+    # The default depends on the root file system. On XFS and ext-4
+    # it is simply `/`. On ZFS and BTRFS it will be a path to a
+    # mounted snapshot of the root file system.
+    #
+    # This can be useful if the root file system supports extra
+    # consistency methods (such as, snapshot support), but the
+    # default backup mechanism cannot use it. For example, because
+    # the file system is not supported by Proxmox VE by default or
+    # taking snapshots comes with an overhead that needs to be
+    # evaluated by the operator.
+    print '{ "base-path": "/path/to/base/path" }';
+
+} elsif ($phase eq 'backup-start') {
+
+    # A backup has been prepared, but nothing has been backed up yet.
+
+    # This stage has a payload that contains the name of the backup
+    # and the backup target. The target is a directory that should
+    # contain all files that should be included in the backup. It
+    # should be created but empty in this phase.
+    #
+    # The payload should be structured as following:
+    # ```js
+    # {
+    #   "backup-name": "host-backup-1234567",
+    #   "backup-target": "/path/to/tmp/backup/dir"
+    # }
+    # ```
+    die "Paylod was undefined.\n" if !defined($payload);
+
+    # Nothing can be communicated back to the job at this stage.
+
+} elsif ($phase eq 'backup-end') {
+
+    # The backup has been completed and uploaded at this stage.
+
+    # A payload should be provided, it will be identical to the
+    # previous stage's payload.
+    die "Paylod was undefined.\n" if !defined($payload);
+
+    # Nothing can be communicated back to the job at this stage.
+
+} elsif ($phase eq 'job-end') {
+
+    # The back up job has completed including cleaning up any
+    # snapshots or temporary files.
+
+    # This stage receives no payload.
+    die "Unknown payload: '$payload'\n" if $payload ne '';
+
+    # Nothing can be communicated back to the job at this stage.
+
+} else {
+    die "Got unknown phase: '$phase'\n";
+}
+
+exit(0);
-- 
2.47.3