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

[Wolfgang Bumiller <w.bumiller@proxmox.com>]

On Fri, Aug 28, 2026 at 03:30:30PM +0200, Shannon Sterz wrote:
> 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);

Paylod -> Payload here and in the case below.

> +
> +    # 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
> 
> 
> 
> 
> 

--