]> git.proxmox.com Git - pve-docs.git/commitdiff
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 f7017f9c6d58563821f0b2a1bac2d3fa3bb9c2f2..2228cbd4ed40165a147c4badfd1d1be89228d869 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
        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)
        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
        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 9fa6a3822974fefd7dba1b32cd45b292e3dc71bd..b5b5af30a75305521df984b048ef2cd9ed54f656 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.
 
 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
 ------------------
 
 Backup and Restore
 ------------------
index b7f3f4d265eed2d57bc76b370f6ff6a90e7b559e..2613d640e28d1e3ac5d2375d841af75e8b87e4bf 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"]
 |==============================================================================
 .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.
 |==============================================================================
 ^[1]^ Snapshots, while no known bugs, cannot be guaranteed to be stable yet, as
 they lack testing.
index bc49fa3e86a614b93729dada656eeecb6db5a48d..7c90cbc3747993734db80f1e1b7a2ada5775645a 100644 (file)
@@ -79,8 +79,8 @@ features available.
 .Storage features for backend `cifs`
 [width="100%",cols="m,m,3*d",options="header"]
 |==============================================================================
 .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
 |==============================================================================
 
 Examples
index 2d6cce533e699119cec89680696f7b8660a08004..090a44b2ee62bb3f5707a001d632c346d55ae5a6 100644 (file)
@@ -39,6 +39,7 @@ storage backends.
 |ISO images          |`template/iso/`
 |Container templates |`template/cache/`
 |Backup files        |`dump/`
 |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"]
 |==============================================================================
 .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 5d72196b4291f064996d34e8e0468d3261e33d81..c3c1b38303899c00357d053aa2029945f624a7dd 100644 (file)
@@ -66,8 +66,8 @@ snapshot/clone implementation.
 .Storage features for backend `glusterfs`
 [width="100%",cols="m,m,3*d",options="header"]
 |==============================================================================
 .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[]
 |==============================================================================
 
 ifdef::wiki[]
index 246de59d73d640fa3cbb48f0437105361685a842..9a900571740febaa2a5671bd95bcfb704fd1a4e6 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"]
 |==============================================================================
 .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
 |==============================================================================
 
 Examples
index cbe496e215d6f186a440fd69d764e8c9f3f8f035..00f3d7ad9942ae788d8564df79c12d82d976d85f 100644 (file)
@@ -211,6 +211,10 @@ iso:::
 
 ISO images
 
 
 ISO images
 
+snippets:::
+
+Snippet files, for example guest hook scripts
+
 shared::
 
 Mark storage as shared.
 shared::
 
 Mark storage as shared.
diff --git a/qm.adoc b/qm.adoc
index 43f250a4d7c7875f526cbd5743a45bf22b04fcd7..30e473f9925757d9294d170537a5a90d730a6dfc 100644 (file)
--- a/qm.adoc
+++ b/qm.adoc
@@ -1030,6 +1030,16 @@ ifndef::wiki[]
 include::qm-pci-passthrough.adoc[]
 endif::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`
 ------------------------------------
 
 Managing Virtual Machines with `qm`
 ------------------------------------