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 <d.csapak@proxmox.com>

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

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);

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

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.

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

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
 |==============================================================================
 
 

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[]

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

pvesm.adoc

@@ -211,6 +211,10 @@ iso:::
 
 ISO images
 
+snippets:::
+
+Snippet files, for example guest hook scripts
+
 shared::
 
 Mark storage as shared.

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`
 ------------------------------------