add documentation about snippet content-type and hookscripts
authorDominik Csapak <d.csapak@proxmox.com>
Thu, 31 Jan 2019 13:33:41 +0000 (14:33 +0100)
committerThomas Lamprecht <t.lamprecht@proxmox.com>
Fri, 1 Feb 2019 12:36:19 +0000 (13:36 +0100)
also add an example perl hookscript, that documents the phases
and arguments

Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
Makefile
guest-example-hookscript.pl [new file with mode: 0755]
pct.adoc
pve-storage-cephfs.adoc
pve-storage-cifs.adoc
pve-storage-dir.adoc
pve-storage-glusterfs.adoc
pve-storage-nfs.adoc
pvesm.adoc
qm.adoc

index f7017f9..2228cbd 100644 (file)
--- 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 (executable)
index 0000000..bc6e403
--- /dev/null
@@ -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);
index 9fa6a38..b5b5af3 100644 (file)
--- 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
 ------------------
index b7f3f4d..2613d64 100644 (file)
@@ -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.
index bc49fa3..7c90cbc 100644 (file)
@@ -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
index 2d6cce5..090a44b 100644 (file)
@@ -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
 |==============================================================================
 
 
index 5d72196..c3c1b38 100644 (file)
@@ -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[]
index 246de59..9a90057 100644 (file)
@@ -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
index cbe496e..00f3d7a 100644 (file)
@@ -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 (file)
--- 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`
 ------------------------------------