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.help | 60 ++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 morphlib/exts/install-files.configure.help

(limited to 'morphlib/exts/install-files.configure.help')

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