[pve-devel] [PATCH docs v4 1/1] add documentation about snippet content-type and hookscripts
Dominik Csapak
d.csapak at proxmox.com
Thu Jan 31 14:33:41 CET 2019
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
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`
------------------------------------
--
2.11.0
More information about the pve-devel
mailing list