[pve-devel] [PATCH docs v4 1/1] add documentation about snippet content-type and hookscripts
Thomas Lamprecht
t.lamprecht at proxmox.com
Fri Feb 1 13:51:51 CET 2019
On 1/31/19 2:33 PM, Dominik Csapak wrote:
> also add an example perl hookscript, that documents the phases
> and arguments
>
> Signed-off-by: Dominik Csapak <d.csapak at proxmox.com>
> ---
> new in v4
> Makefile | 4 ++-
> guest-example-hookscript.pl | 61 +++++++++++++++++++++++++++++++++++++++++++++
> pct.adoc | 10 ++++++++
> pve-storage-cephfs.adoc | 4 +--
> pve-storage-cifs.adoc | 4 +--
> pve-storage-dir.adoc | 5 ++--
> pve-storage-glusterfs.adoc | 4 +--
> pve-storage-nfs.adoc | 4 +--
> pvesm.adoc | 4 +++
> qm.adoc | 10 ++++++++
> 10 files changed, 99 insertions(+), 11 deletions(-)
> create mode 100755 guest-example-hookscript.pl
applied, but moved the script in it's own examples dir as I do not like
the flat very crowded directory/file structure in docs and it's somewhat
reasonable to suspect that there may come more examples.
>
> diff --git a/Makefile b/Makefile
> index f7017f9..2228cbd 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -186,12 +186,14 @@ gen-install: $(GEN_DEB_SOURCES) asciidoc-pve asciidoc/mediawiki.conf
> install -m 0644 asciidoc/pve-html.conf $(DESTDIR)/usr/share/${GEN_PACKAGE}/asciidoc/
>
> .PHONY: doc-install
> -doc-install: index.html $(WIKI_IMPORTS) $(API_VIEWER_SOURCES) verify-images
> +doc-install: index.html $(WIKI_IMPORTS) $(API_VIEWER_SOURCES) verify-images guest-example-hookscript.pl
> install -dm755 $(DESTDIR)/usr/share/$(DOC_PACKAGE)
> install -dm755 $(DESTDIR)/usr/share/doc/$(DOC_PACKAGE)
> # install files for pvedocs package
> install -dm755 $(DESTDIR)/usr/share/${DOC_PACKAGE}
> install -dm755 $(DESTDIR)/usr/share/doc/${DOC_PACKAGE}
> + install -dm755 $(DESTDIR)/usr/share/${DOC_PACKAGE}/examples/
> + install -m 755 guest-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/guest-example-hookscript.pl b/guest-example-hookscript.pl
> new file mode 100755
> index 0000000..bc6e403
> --- /dev/null
> +++ b/guest-example-hookscript.pl
> @@ -0,0 +1,61 @@
> +#!/usr/bin/perl
> +
> +# Exmple hook script for PVE guests (hookscript config option)
> +# You can set this via pct/qm with
> +# pct set <vmid> -hookscript <volume-id>
> +# qm set <vmid> -hookscript <volume-id>
> +# where <volume-id> has to be an executable file in the snippets folder
> +# of any storage with directories e.g.:
> +# qm set 100 -hookscript local:snippets/hookscript.pl
> +
> +use strict;
> +use warnings;
> +
> +print "GUEST HOOK: " . join(' ', @ARGV). "\n";
> +
> +# First argument is the vmid
> +
> +my $vmid = shift;
> +
> +# Second argument is the phase
> +
> +my $phase = shift;
> +
> +if ($phase eq 'pre-start') {
> +
> + # First phase 'pre-start' will be executed before the guest
> + # ist started. Exiting with a code != 0 will abort the start
> +
> + print "$vmid is starting, doing preparations.\n";
> +
> + # print "preparations failed, aborting."
> + # exit(1);
> +
> +} elsif ($phase eq 'post-start') {
> +
> + # Second phase 'post-start' will be executed after the guest
> + # successfully started.
> +
> + print "$vmid started successfully.\n";
> +
> +} elsif ($phase eq 'pre-stop') {
> +
> + # Third phase 'pre-stop' will be executed before stopping the guest
> + # via the API. Will not be executed if the guest is stopped from
> + # within e.g., with a 'poweroff'
> +
> + print "$vmid will be stopped.\n";
> +
> +} elsif ($phase eq 'post-stop') {
> +
> + # Last phase 'post-stop' will be executed after the guest stopped.
> + # This should even be executed in case the guest crashes or stopped
> + # unexpectedly.
> +
> + print "$vmid stopped. Doing cleanup.\n";
> +
> +} else {
> + die "got unknown phase '$phase'\n";
> +}
> +
> +exit(0);
> diff --git a/pct.adoc b/pct.adoc
> index 9fa6a38..b5b5af3 100644
> --- a/pct.adoc
> +++ b/pct.adoc
> @@ -590,6 +590,16 @@ start after those where the parameter is set, and this parameter only
> makes sense between the machines running locally on a host, and not
> cluster-wide.
>
> +Hookscripts
> +~~~~~~~~~~~
> +
> +You can add a hook script to CTs with the config property `hookscript`.
> +
> + pct set 100 -hookscript local:snippets/hookscript.pl
> +
> +It will be called during various phases of the guests lifetime.
> +For an example and documentation see the example script under
> +`/usr/share/pve-docs/examples/guest-example-hookscript.pl`.
>
> Backup and Restore
> ------------------
> diff --git a/pve-storage-cephfs.adoc b/pve-storage-cephfs.adoc
> index b7f3f4d..2613d64 100644
> --- a/pve-storage-cephfs.adoc
> +++ b/pve-storage-cephfs.adoc
> @@ -89,8 +89,8 @@ The `cephfs` backend is a POSIX-compliant filesystem on top of a Ceph cluster.
> .Storage features for backend `cephfs`
> [width="100%",cols="m,m,3*d",options="header"]
> |==============================================================================
> -|Content types |Image formats |Shared |Snapshots |Clones
> -|vztmpl iso backup |none |yes |yes^[1]^ |no
> +|Content types |Image formats |Shared |Snapshots |Clones
> +|vztmpl iso backup snippets |none |yes |yes^[1]^ |no
> |==============================================================================
> ^[1]^ Snapshots, while no known bugs, cannot be guaranteed to be stable yet, as
> they lack testing.
> diff --git a/pve-storage-cifs.adoc b/pve-storage-cifs.adoc
> index bc49fa3..7c90cbc 100644
> --- a/pve-storage-cifs.adoc
> +++ b/pve-storage-cifs.adoc
> @@ -79,8 +79,8 @@ features available.
> .Storage features for backend `cifs`
> [width="100%",cols="m,m,3*d",options="header"]
> |==============================================================================
> -|Content types |Image formats |Shared |Snapshots |Clones
> -|images rootdir vztmpl iso backup |raw qcow2 vmdk |yes |qcow2 |qcow2
> +|Content types |Image formats |Shared |Snapshots |Clones
> +|images rootdir vztmpl iso backup snippets |raw qcow2 vmdk |yes |qcow2 |qcow2
> |==============================================================================
>
> Examples
> diff --git a/pve-storage-dir.adoc b/pve-storage-dir.adoc
> index 2d6cce5..090a44b 100644
> --- a/pve-storage-dir.adoc
> +++ b/pve-storage-dir.adoc
> @@ -39,6 +39,7 @@ storage backends.
> |ISO images |`template/iso/`
> |Container templates |`template/cache/`
> |Backup files |`dump/`
> +|Snippets |`snippets/`
> |===========================================================
>
>
> @@ -107,8 +108,8 @@ feature to create clones.
> .Storage features for backend `dir`
> [width="100%",cols="m,m,3*d",options="header"]
> |==============================================================================
> -|Content types |Image formats |Shared |Snapshots |Clones
> -|images rootdir vztmpl iso backup |raw qcow2 vmdk subvol |no |qcow2 |qcow2
> +|Content types |Image formats |Shared |Snapshots |Clones
> +|images rootdir vztmpl iso backup snippets |raw qcow2 vmdk subvol |no |qcow2 |qcow2
> |==============================================================================
>
>
> diff --git a/pve-storage-glusterfs.adoc b/pve-storage-glusterfs.adoc
> index 5d72196..c3c1b38 100644
> --- a/pve-storage-glusterfs.adoc
> +++ b/pve-storage-glusterfs.adoc
> @@ -66,8 +66,8 @@ snapshot/clone implementation.
> .Storage features for backend `glusterfs`
> [width="100%",cols="m,m,3*d",options="header"]
> |==============================================================================
> -|Content types |Image formats |Shared |Snapshots |Clones
> -|images vztmpl iso backup |raw qcow2 vmdk |yes |qcow2 |qcow2
> +|Content types |Image formats |Shared |Snapshots |Clones
> +|images vztmpl iso backup snippets |raw qcow2 vmdk |yes |qcow2 |qcow2
> |==============================================================================
>
> ifdef::wiki[]
> diff --git a/pve-storage-nfs.adoc b/pve-storage-nfs.adoc
> index 246de59..9a90057 100644
> --- a/pve-storage-nfs.adoc
> +++ b/pve-storage-nfs.adoc
> @@ -69,8 +69,8 @@ to implement snapshots and cloning.
> .Storage features for backend `nfs`
> [width="100%",cols="m,m,3*d",options="header"]
> |==============================================================================
> -|Content types |Image formats |Shared |Snapshots |Clones
> -|images rootdir vztmpl iso backup |raw qcow2 vmdk |yes |qcow2 |qcow2
> +|Content types |Image formats |Shared |Snapshots |Clones
> +|images rootdir vztmpl iso backup snippets |raw qcow2 vmdk |yes |qcow2 |qcow2
> |==============================================================================
>
> Examples
> diff --git a/pvesm.adoc b/pvesm.adoc
> index cbe496e..00f3d7a 100644
> --- a/pvesm.adoc
> +++ b/pvesm.adoc
> @@ -211,6 +211,10 @@ iso:::
>
> ISO images
>
> +snippets:::
> +
> +Snippet files, for example guest hook scripts
> +
> shared::
>
> Mark storage as shared.
> diff --git a/qm.adoc b/qm.adoc
> index 43f250a..30e473f 100644
> --- a/qm.adoc
> +++ b/qm.adoc
> @@ -1030,6 +1030,16 @@ ifndef::wiki[]
> include::qm-pci-passthrough.adoc[]
> endif::wiki[]
>
> +Hookscripts
> +~~~~~~~~~~~
> +
> +You can add a hook script to VMs with the config property `hookscript`.
> +
> + qm set 100 -hookscript local:snippets/hookscript.pl
> +
> +It will be called during various phases of the guests lifetime.
> +For an example and documentation see the example script under
> +`/usr/share/pve-docs/examples/guest-example-hookscript.pl`.
>
> Managing Virtual Machines with `qm`
> ------------------------------------
>
More information about the pve-devel
mailing list