From 2876765436d2f1c1e89d5e7326d9b5812ad5eb00 Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Sat, 4 Apr 2015 20:35:33 +0100
Subject: [PATCH] docs: Add documentation for template files.

---
 mclu.pod | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 104 insertions(+), 3 deletions(-)

diff --git a/mclu.pod b/mclu.pod
index 081d233..51d216e 100644
--- a/mclu.pod
+++ b/mclu.pod
@@ -48,9 +48,6 @@ Display version number and exit.
 
 =back
 
-
-
-
 =head1 SUBCOMMANDS
 
 =over 4
@@ -172,8 +169,112 @@ Open the graphical console of the guest (using L<virt-viewer(1)>).
 
 =head1 TEMPLATE FILES
 
+Template files are shell scripts which the C<mclu> program calls to
+perform various operations.
+
+Template files must have the extension C<.template>, must be
+executable (C<chmod +x *.template>), and they must live in the
+template directory (usually found through the C<$MCLU_PATH>
+environment variable).
+
+Several template files are supplied with mclu sources, and it's a good
+idea to consult those for examples and when creating your own
+templates.
+
+C<mclu> runs the template with a single parameter in order to "query"
+the template.  All templates must support the C<probe> parameter,
+which is used to test that the file is a template:
+
+ $ ./templates/rawhide.template probe
+ hello
+
+Templates should exit with code 2 if they don't know about a parameter:
+
+ $ ./templates/rawhide.template unknown
+ $ echo $?
+ 2
+
+The current parameters are:
+
+=over 4
+
+=item base-image
+
+The template MUST print the name of the image that it builds.  The
+meaning of this generally follows the conventions of
+L<virt-builder(1)>, if virt-builder is used by the template.
+
+=item build
+
+The template MUST build a disk image.  Because the C<template build>
+command could run on any node in the cluster, it won't necessarily
+have access to other local files on the same node that C<mclu> is
+running on.
+
+The following environment variables are passed to the template:
+
+=over 4
+
+=item C<$base_image>
+
+The name of the base image.  This is the output of the C<base-image>
+probe.
+
+=item C<$format>
+
+The output format (eg. C<qcow2>).
 
+=item C<$name>
 
+The hostname.
+
+=item C<$output>
+
+The output file.
+
+=item C<$size>
+
+(Optionally) The output size (in bytes).  If not specified, then the
+template can choose a default size.
+
+=item C<$timezone>
+
+(Optionally) The timezone.
+
+=back
+
+=item disk-bus
+
+The template MAY print the disk type supported by this guest.  Possible
+values include C<ide>, C<virtio>, C<virtio-scsi>.
+
+=item minimum-memory
+
+The template MAY print the minimum memory (RAM) required by this
+guest.  Abbreviations like C<1G> are supported.
+
+=item minimum-size
+
+The template MAY print the minimum disk space required by this guest.
+Abbreviations like C<10G> are supported.
+
+=item network-model
+
+The template MAY print the network type supported by this guest.
+Possible values include C<e1000>, C<virtio>.
+
+=item probe
+
+The template MUST print C<hello> followed by a newline, and then exit
+with code 0.
+
+=item recommended-memory
+
+The template MAY print the recommended amount of memory (RAM), used if
+the user does not select any other value.  Abbreviations like C<2G>
+are supported.
+
+=back
 
 =head1 ENVIRONMENT VARIABLES
 
-- 
1.8.3.1