From 949788092824768dc5ffd517073b5b94172869ee Mon Sep 17 00:00:00 2001
From: Richard Ipsum <richard.ipsum@codethink.co.uk>
Date: Thu, 8 May 2014 18:43:15 +0100
Subject: Add help for install-files.configure

Move the help out of the comment and into a help file,
and add a clearer example.
---
 morphlib/exts/install-files.configure      | 28 --------------
 morphlib/exts/install-files.configure.help | 60 ++++++++++++++++++++++++++++++
 2 files changed, 60 insertions(+), 28 deletions(-)
 create mode 100644 morphlib/exts/install-files.configure.help

diff --git a/morphlib/exts/install-files.configure b/morphlib/exts/install-files.configure
index 8ba61b4e..04dc5f18 100755
--- a/morphlib/exts/install-files.configure
+++ b/morphlib/exts/install-files.configure
@@ -33,34 +33,6 @@ import stat
 
 class InstallFilesConfigureExtension(cliapp.Application):
 
-    '''Install the files specified in the manifests listed in INSTALL_FILES
-
-    Entries in the manifest are formatted as:
-
-        [overwrite] <octal mode> <uid decimal> <gid decimal> <filename>
-
-    Where the filename is how the file is found inside whatever directory
-    the manifest is stored in, and also the path within the system to
-    install to.
-
-    Directories on the target must be created if they do not exist.
-    
-    This extension supports files, symlinks and directories.
-
-    For example,
-
-        0100644 0 0 /etc/issue
-
-        creates a regular file at /etc/issue with 644 permissions,
-        uid 0 and gid 0, if the file doesn't already exist.
-
-        overwrite 0100644 0 0 /etc/issue
-
-        creates a regular file at /etc/issue with 644 permissions,
-        uid 0 and gid 0, if the file already exists it is overwritten.
-
-    '''
-
     def process_args(self, args):
         if not 'INSTALL_FILES' in os.environ:
             return
diff --git a/morphlib/exts/install-files.configure.help b/morphlib/exts/install-files.configure.help
new file mode 100644
index 00000000..eb3aab0c
--- /dev/null
+++ b/morphlib/exts/install-files.configure.help
@@ -0,0 +1,60 @@
+help: |
+    Install a set of files onto a system
+
+    To use this extension you create a directory of files you want to install
+    onto the target system.
+
+    In this example we want to copy some ssh keys onto a system
+
+        % mkdir sshkeyfiles
+        % mkdir -p sshkeyfiles/root/.ssh
+        % cp id_rsa sshkeyfiles/root/.ssh
+        % cp id_rsa.pub sshkeyfiles/root/.ssh
+
+    Now we need to create a manifest file to set the file modes
+    and persmissions. The manifest file should be created inside the
+    directory that contains the files we're trying to install.
+
+        cat << EOF > sshkeyfiles/manifest
+        0040755 0 0 /root/.ssh
+        0100600 0 0 /root/.ssh/id_rsa
+        0100644 0 0 /root/.ssh/id_rsa.pub
+        EOF
+
+    Then we add the path to our manifest to our cluster morph,
+    this path should be relative to the system definitions repository.
+
+        INSTALL_FILES: sshkeysfiles/manifest
+
+    More generally entries in the manifest are formatted as:
+        [overwrite] <octal mode> <uid decimal> <gid decimal> <filename>
+
+    NOTE: Directories on the target must be created if they do not exist.
+
+    The extension supports files, symlinks and directories.
+
+    For example,
+
+        0100644 0 0 /etc/issue
+
+    creates a regular file at /etc/issue with 644 permissions,
+    uid 0 and gid 0, if the file doesn't already exist.
+
+        overwrite 0100644 0 0 /etc/issue
+
+    creates a regular file at /etc/issue with 644 permissions,
+    uid 0 and gid 0, if the file already exists it is overwritten.
+
+        0100755 0 0 /usr/bin/foo
+
+    creates an executable file at /usr/bin/foo
+
+        0040755 0 0 /etc/foodir
+
+    creates a directory with 755 permissions
+
+        0120000 0 0 /usr/bin/bar
+
+    creates a symlink at /usr/bin/bar
+
+    NOTE: You will still need to make a symlink in the manifest directory.
-- 
cgit v1.2.1