[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