Browse Source

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>
stable-5
Dominik Csapak 9 months ago
parent
commit
c2c8eb89d1
10 changed files with 99 additions and 11 deletions
  1. 3
    1
      Makefile
  2. 61
    0
      guest-example-hookscript.pl
  3. 10
    0
      pct.adoc
  4. 2
    2
      pve-storage-cephfs.adoc
  5. 2
    2
      pve-storage-cifs.adoc
  6. 3
    2
      pve-storage-dir.adoc
  7. 2
    2
      pve-storage-glusterfs.adoc
  8. 2
    2
      pve-storage-nfs.adoc
  9. 4
    0
      pvesm.adoc
  10. 10
    0
      qm.adoc

+ 3
- 1
Makefile View File

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

+ 61
- 0
guest-example-hookscript.pl View File

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

+ 10
- 0
pct.adoc View File

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

+ 2
- 2
pve-storage-cephfs.adoc View 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.

+ 2
- 2
pve-storage-cifs.adoc View 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

+ 3
- 2
pve-storage-dir.adoc View 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
|==============================================================================



+ 2
- 2
pve-storage-glusterfs.adoc View 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[]

+ 2
- 2
pve-storage-nfs.adoc View 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

+ 4
- 0
pvesm.adoc View File

@@ -211,6 +211,10 @@ iso:::

ISO images

snippets:::

Snippet files, for example guest hook scripts

shared::

Mark storage as shared.

+ 10
- 0
qm.adoc View File

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

Loading…
Cancel
Save