install: Write chapter 9

1 files changed, 70 insertions, 3 deletions

diff --git a/src/install/9_image.xml b/src/install/9_image.xml
index f178334..ce69b7c 100644
--- a/src/install/9_image.xml
+++ b/src/install/9_image.xml
@@ -1,8 +1,75 @@
 <?xml version="1.0" encoding="utf-8"?>
 <chapter label="9" id="image">
     <title>Creating Images</title>
-    <section>
-        <title/>
-        <para/>
+    <highlights><para>You can use the Image Creation system to create various types of images, including bootable CD/USB images and root filesystem tarballs you can deploy later.</para></highlights>
+    <section id="image_basics">
+        <title>Using the Image Creation System</title>
+        <para>The Image Creation system takes a HorizonScript as input, and uses it to generate an image of the desired type.  The primary command for interacting with the Image Creation system is <literal><command>hscript-image</command></literal>.</para>
+        <para>You can view a list of available image types by running <literal><command>hscript-image</command> -t list</literal>.  The <literal>hscript-image</literal> command will print a list of available image types.  The first column contains the <firstterm>type code</firstterm> which you pass to the <literal>-t</literal> paramater, and the second column provides you a short explanation of what type of image will be created with the specified type code.</para>
+        <para>The output file name can be controlled by the <literal>-o</literal> parameter.  For example, <literal><command>hscript-image</command> -t iso -o mydisc.iso</literal> will write the image to <filename>mydisc.iso</filename>.</para>
+        <para>Backend-specific options can be specified using the <literal>-b</literal> parameter.  You may specify the <literal>-b</literal> parameter multiple times, to provide multiple options to the specified backend.  Backend-specific options are discussed later in the per-backend sections.</para>
+        <para>Temporary files, including the entire image root directory, are written to a directory called the <firstterm>intermediate directory</firstterm>, or <firstterm>IR directory</firstterm>.  The default path for this is <filename class="directory">/tmp/horizon-image</filename>; you may specify the <literal>-i</literal> parameter to change it.  For example, <literal><command>hscript-image</command> -i /opt/horizon/imagedir</literal> will write the temporary files to <literal>/opt/horizon/imagedir</literal>.  The temporary files are not removed after running the <literal><command>hscript-image</command></literal> command, whether or not the run was successful.  This allows you to inspect the contents of the image without extracting them.  You may remove the directory at any time after the <command>hscript-image</command> process ends.</para>
+    </section>
+    <section id="image_backends">
+        <title>Backend-Specific Options</title>
+        <para>Each backend in the Image Creation system has its own set of defaults and available options.  The backends provided with the Horizon system are documented in this section.</para>
+        <section id="image_tar">
+            <title>Archive Backend (tar, tgz, tbz, txz)</title>
+            <para>No backend-specific options are available for the libarchive backend.</para>
+        </section>
+        <section id="image_iso">
+            <title>ISO Backend (iso)</title>
+            <para>
+                <variablelist>
+                    <title>Available options for the ISO backend</title>
+                    <varlistentry>
+                        <term><literal>keep</literal></term>
+                        <listitem><para>Preserve the IR directory between runs.  This can save significant time downloading packages if you are using a slow connection, but does not support HorizonScripts that contain user accounts other than <literal>root</literal>.</para></listitem>
+                    </varlistentry>
+                    <varlistentry>
+                        <term><literal>issue-path=<userinput>/path/to/issue</userinput></literal></term>
+                        <listitem><para>Specifies the location of the file that will be used as <filename>/etc/issue</filename> for the CD's operating environment.  <userinput>/path/to/issue</userinput> should be a plain text file that exists on the current system.</para></listitem>
+                    </varlistentry>
+                    <varlistentry>
+                        <term><literal>icon-path=<userinput>/path/to/icns</userinput></literal></term>
+                        <listitem><para>Specifies the location of the file that will be used as <filename>.VolumeIcon.icns</filename> for the CD.  <userinput>/path/to/icns</userinput> should be a ICNS file that exists on the current system.</para></listitem>
+                    </varlistentry>
+                    <varlistentry>
+                        <term><literal>post-script=<userinput>/path/to/script.sh</userinput></literal></term>
+                        <listitem><para>Specifies the location of the file that will be executed just before creating the actual ISO file.  <userinput>/path/to/script.sh</userinput> should be an executable file that exists on the current system.  A default script is provided for all Tier 1 architectures that correctly configures boot parameters.  You should only override this script if you know exactly what you are doing.</para></listitem>
+                    </varlistentry>
+                    <varlistentry>
+                        <term><literal>iso-params="<userinput>parameter1 parameter2=value ...</userinput>"</literal></term>
+                        <listitem><para>Specifies additional parameters to pass to <literal><command>xorriso</command></literal>.</para></listitem>
+                    </varlistentry>
+                </variablelist>
+            </para>
+        </section>
+    </section>
+    <section id="image_custom">
+        <title>Writing a Custom Backend</title>
+        <para>The Image Creation system is easily extensible.  You can check out the Horizon source code and add a new backend with minimal effort.  The <filename class="directory">image/backends</filename> includes a README that describes the basic design of backend modules.  The libarchive backend is also a good example to use; the entire module is only 188 lines of C++.</para>
+        <section id="image_custom_register">
+            <title>Registering Your Custom Backend</title>
+            <para>Your backend module needs to have a <firstterm>constructor function</firstterm> (unrelated to C++ class constructors) that registers the backend with the Image Creation system.  You must call <literal>Horizon::Image::BackendManager::register_backend</literal> from your constructor function to register your backend.  The following is a short example based on the libarchive backend.</para>
+            <example>
+                <title>Registering a custom backend in a constructor function</title>
+                <programlisting>
+#include &lt;image/backends/basic.hh&gt;
+#include "xyzzy.hh"
+
+__attribute__((constructor(400)))
+void register_xyzzy_backend() {
+    Horizon::Image::BackendManager::register_backend(
+    {"xyzzy", "Create an XYZZY image (.xyzzy)",
+        [](const std::string &amp;ir_dir, const std::string &amp;out_path,
+           const std::map&lt;std::string, std::string&gt; &amp;opts) {
+            return new XyzzyBackend(ir_dir, out_path, opts);
+        }
+    });
+}
+                </programlisting>
+            </example>
+        </section>
     </section>
 </chapter>