1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
|
<?xml version="1.0" encoding="utf-8"?>
<chapter label="9" id="image">
<title>Creating Images</title>
<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>
<para>Specify the installfile at the end of the command line. For example, <literal><command>hscript-image</command> -t iso -o mydisc.iso $HOME/mydisc.installfile</literal> will use the script located at <userinput>$HOME/mydisc.installfile</userinput>. If you do not specify an installfile, the one at <literal>/etc/horizon/installfile</literal> will be used. You may also specify <literal>-</literal> to use <literal>stdin</literal>.</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 <image/backends/basic.hh>
#include "xyzzy.hh"
__attribute__((constructor(400)))
void register_xyzzy_backend() {
Horizon::Image::BackendManager::register_backend(
{"xyzzy", "Create an XYZZY image (.xyzzy)",
[](const std::string &ir_dir, const std::string &out_path,
const std::map<std::string, std::string> &opts) {
return new XyzzyBackend(ir_dir, out_path, opts);
}
});
}
</programlisting>
</example>
</section>
</section>
</chapter>
|
