From: Dominik Csapak Date: Thu, 31 Jan 2019 13:33:41 +0000 (+0100) Subject: add documentation about snippet content-type and hookscripts X-Git-Url: https://git.proxmox.com/?p=pve-docs.git;a=commitdiff_plain;h=c2c8eb89d18ca2482319eb9d1584c91dc07c0d24 add documentation about snippet content-type and hookscripts also add an example perl hookscript, that documents the phases and arguments Signed-off-by: Dominik Csapak --- 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 -hookscript +# qm set -hookscript +# where 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` ------------------------------------