466 lines
35 KiB
HTML
466 lines
35 KiB
HTML
|
|
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
|
|
<title>lorax-composer — Lorax 19.7.22 documentation</title>
|
|
|
|
<link rel="stylesheet" href="_static/default.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
|
|
<script type="text/javascript">
|
|
var DOCUMENTATION_OPTIONS = {
|
|
URL_ROOT: '',
|
|
VERSION: '19.7.22',
|
|
COLLAPSE_INDEX: false,
|
|
FILE_SUFFIX: '.html',
|
|
HAS_SOURCE: true
|
|
};
|
|
</script>
|
|
<script type="text/javascript" src="_static/jquery.js"></script>
|
|
<script type="text/javascript" src="_static/underscore.js"></script>
|
|
<script type="text/javascript" src="_static/doctools.js"></script>
|
|
<link rel="top" title="Lorax 19.7.22 documentation" href="index.html" />
|
|
<link rel="next" title="composer-cli" href="composer-cli.html" />
|
|
<link rel="prev" title="livemedia-creator" href="livemedia-creator.html" />
|
|
</head>
|
|
<body>
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="genindex.html" title="General Index"
|
|
accesskey="I">index</a></li>
|
|
<li class="right" >
|
|
<a href="py-modindex.html" title="Python Module Index"
|
|
>modules</a> |</li>
|
|
<li class="right" >
|
|
<a href="composer-cli.html" title="composer-cli"
|
|
accesskey="N">next</a> |</li>
|
|
<li class="right" >
|
|
<a href="livemedia-creator.html" title="livemedia-creator"
|
|
accesskey="P">previous</a> |</li>
|
|
<li><a href="index.html">Lorax 19.7.22 documentation</a> »</li>
|
|
</ul>
|
|
</div>
|
|
|
|
<div class="document">
|
|
<div class="documentwrapper">
|
|
<div class="bodywrapper">
|
|
<div class="body">
|
|
|
|
<div class="section" id="lorax-composer">
|
|
<h1>lorax-composer<a class="headerlink" href="#lorax-composer" title="Permalink to this headline">¶</a></h1>
|
|
<table class="docutils field-list" frame="void" rules="none">
|
|
<col class="field-name" />
|
|
<col class="field-body" />
|
|
<tbody valign="top">
|
|
<tr class="field-odd field"><th class="field-name">Authors:</th><td class="field-body">Brian C. Lane <<a class="reference external" href="mailto:bcl%40redhat.com">bcl<span>@</span>redhat<span>.</span>com</a>></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<p><tt class="docutils literal"><span class="pre">lorax-composer</span></tt> is an API server that allows you to build disk images using
|
|
<a class="reference internal" href="#blueprints">Blueprints</a> to describe the package versions to be installed into the image.
|
|
It is compatible with the Weldr project’s bdcs-api REST protocol. More
|
|
information on Weldr can be found <a class="reference external" href="http://www.weldr.io">on the Weldr blog</a>.</p>
|
|
<p>Behind the scenes it uses <a class="reference external" href="livemedia-creator.html">livemedia-creator</a> and
|
|
<a class="reference external" href="https://anaconda-installer.readthedocs.io/en/latest/">Anaconda</a> to handle the
|
|
installation and configuration of the images.</p>
|
|
<div class="section" id="important-things-to-note">
|
|
<h2>Important Things To Note<a class="headerlink" href="#important-things-to-note" title="Permalink to this headline">¶</a></h2>
|
|
<ul class="simple">
|
|
<li>SELinux must be in Permissive mode. Anaconda requires SELinux be in permissive mode
|
|
for image creation to work correctly. You can either edit the setting in the
|
|
<tt class="docutils literal"><span class="pre">/etc/sysconfig/selinux</span></tt> file, or run <tt class="docutils literal"><span class="pre">setenforce</span> <span class="pre">0</span></tt> before starting lorax-composer.</li>
|
|
<li>Some output types require packages from the RHEL 7 Optional repository. See the
|
|
<a class="reference external" href="https://access.redhat.com/solutions/392003">Red Hat Enterprise Linux 7 documentation</a>
|
|
for information on how to enable it. Otherwise you will see image creation fail to
|
|
depsolve even if the blueprint itself is correct.</li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="installation">
|
|
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
|
|
<p>The best way to install <tt class="docutils literal"><span class="pre">lorax-composer</span></tt> is to use <tt class="docutils literal"><span class="pre">sudo</span> <span class="pre">dnf</span> <span class="pre">install</span>
|
|
<span class="pre">lorax-composer</span> <span class="pre">composer-cli</span></tt>, this will setup the weldr user and install the
|
|
systemd socket activation service. You will then need to enable it with <tt class="docutils literal"><span class="pre">sudo</span>
|
|
<span class="pre">systemctl</span> <span class="pre">enable</span> <span class="pre">lorax-composer.socket</span> <span class="pre">&&</span> <span class="pre">sudo</span> <span class="pre">systemctl</span> <span class="pre">start</span>
|
|
<span class="pre">lorax-composer.socket</span></tt>. This will leave the server off until the first request
|
|
is made. Systemd will then launch the server and it will remain running until
|
|
the system is rebooted. This will cause some delay in responding to the first
|
|
request from the UI or <cite>composer-cli</cite>.</p>
|
|
<div class="admonition note">
|
|
<p class="first admonition-title">Note</p>
|
|
<p class="last">If you want lorax-composer to respond immediately to the first request you can
|
|
start and enable <cite>lorax-composer.service</cite> instead of <cite>lorax-composer.socket</cite></p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="quickstart">
|
|
<h2>Quickstart<a class="headerlink" href="#quickstart" title="Permalink to this headline">¶</a></h2>
|
|
<ol class="arabic simple">
|
|
<li>Create a <tt class="docutils literal"><span class="pre">weldr</span></tt> user and group by running <tt class="docutils literal"><span class="pre">useradd</span> <span class="pre">weldr</span></tt></li>
|
|
<li>Remove any pre-existing socket directory with <tt class="docutils literal"><span class="pre">rm</span> <span class="pre">-rf</span> <span class="pre">/run/weldr/</span></tt>
|
|
A new directory with correct permissions will be created the first time the server runs.</li>
|
|
<li>Enable the socket activation with <tt class="docutils literal"><span class="pre">systemctl</span> <span class="pre">enable</span> <span class="pre">lorax-composer.socket</span>
|
|
<span class="pre">&&</span> <span class="pre">sudo</span> <span class="pre">systemctl</span> <span class="pre">start</span> <span class="pre">lorax-composer.socket</span></tt>.</li>
|
|
</ol>
|
|
<p>NOTE: You can also run it directly with <tt class="docutils literal"><span class="pre">lorax-composer</span> <span class="pre">/path/to/blueprints</span></tt>. However,
|
|
<tt class="docutils literal"><span class="pre">lorax-composer</span></tt> does not react well to being started both on the command line and via
|
|
socket activation at the same time. It is therefore recommended that you run it directly
|
|
on the command line only for testing or development purposes. For real use or development
|
|
of other projects that simply use the API, you should stick to socket activation only.</p>
|
|
<p>The <tt class="docutils literal"><span class="pre">/path/to/blueprints/</span></tt> directory is where the blueprints’ git repo will
|
|
be created, and all the blueprints created with the <tt class="docutils literal"><span class="pre">/api/v0/blueprints/new</span></tt>
|
|
route will be stored. If there are blueprint <tt class="docutils literal"><span class="pre">.toml</span></tt> files in the top level
|
|
of the directory they will be imported into the blueprint git storage when
|
|
<tt class="docutils literal"><span class="pre">lorax-composer</span></tt> starts.</p>
|
|
</div>
|
|
<div class="section" id="logs">
|
|
<h2>Logs<a class="headerlink" href="#logs" title="Permalink to this headline">¶</a></h2>
|
|
<p>Logs are stored under <tt class="docutils literal"><span class="pre">/var/log/lorax-composer/</span></tt> and include all console
|
|
messages as well as extra debugging info and API requests.</p>
|
|
</div>
|
|
<div class="section" id="security">
|
|
<h2>Security<a class="headerlink" href="#security" title="Permalink to this headline">¶</a></h2>
|
|
<p>Some security related issues that you should be aware of before running <tt class="docutils literal"><span class="pre">lorax-composer</span></tt>:</p>
|
|
<ul class="simple">
|
|
<li>One of the API server threads needs to retain root privileges in order to run Anaconda.</li>
|
|
<li>SELinux must be set to Permissive or disabled to allow <tt class="docutils literal"><span class="pre">livemedia-creator</span></tt> to run Anaconda.</li>
|
|
<li>Only allow authorized users access to the <tt class="docutils literal"><span class="pre">weldr</span></tt> group and socket.</li>
|
|
</ul>
|
|
<p>Since Anaconda kickstarts are used there is the possibility that a user could
|
|
inject commands into a blueprint that would result in the kickstart executing
|
|
arbitrary code on the host. Only authorized users should be allowed to build
|
|
images using <tt class="docutils literal"><span class="pre">lorax-composer</span></tt>.</p>
|
|
</div>
|
|
<div class="section" id="how-it-works">
|
|
<h2>How it Works<a class="headerlink" href="#how-it-works" title="Permalink to this headline">¶</a></h2>
|
|
<p>The server runs as root, and as <tt class="docutils literal"><span class="pre">weldr</span></tt>. Communication with it is via a unix
|
|
domain socket (<tt class="docutils literal"><span class="pre">/run/weldr/api.socket</span></tt> by default). The directory and socket
|
|
are owned by <tt class="docutils literal"><span class="pre">root:weldr</span></tt> so that any user in the <tt class="docutils literal"><span class="pre">weldr</span></tt> group can use the API
|
|
to control <tt class="docutils literal"><span class="pre">lorax-composer</span></tt>.</p>
|
|
<p>At startup the server will check for the correct permissions and
|
|
ownership of a pre-existing directory, or it will create a new one if it
|
|
doesn’t exist. The socket path and group owner’s name can be changed from the
|
|
cmdline by passing it the <tt class="docutils literal"><span class="pre">--socket</span></tt> and <tt class="docutils literal"><span class="pre">--group</span></tt> arguments.</p>
|
|
<p>It will then drop root privileges for the API thread and run as the <tt class="docutils literal"><span class="pre">weldr</span></tt>
|
|
user. The queue and compose thread still runs as root because it needs to be
|
|
able to mount/umount files and run Anaconda.</p>
|
|
</div>
|
|
<div class="section" id="composing-images">
|
|
<h2>Composing Images<a class="headerlink" href="#composing-images" title="Permalink to this headline">¶</a></h2>
|
|
<p>The <a class="reference external" href="https://github.com/weldr/welder-web/">welder-web</a> GUI project can be used to construct
|
|
blueprints and create composes using a web browser.</p>
|
|
<p>Or use the command line with <a class="reference external" href="composer-cli.html">composer-cli</a>.</p>
|
|
</div>
|
|
<div class="section" id="blueprints">
|
|
<h2>Blueprints<a class="headerlink" href="#blueprints" title="Permalink to this headline">¶</a></h2>
|
|
<p>Blueprints are simple text files in <a class="reference external" href="https://github.com/toml-lang/toml">TOML</a> format that describe
|
|
which packages, and what versions, to install into the image. They can also define a limited set
|
|
of customizations to make to the final image.</p>
|
|
<p>Example blueprints can be found in the <tt class="docutils literal"><span class="pre">lorax-composer</span></tt> <a class="reference external" href="https://github.com/weldr/lorax/tree/master/tests/pylorax/blueprints/">test suite</a>, with a simple one
|
|
looking like this:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="n">name</span> <span class="o">=</span> <span class="s">"base"</span>
|
|
<span class="n">description</span> <span class="o">=</span> <span class="s">"A base system with bash"</span>
|
|
<span class="n">version</span> <span class="o">=</span> <span class="s">"0.0.1"</span>
|
|
|
|
<span class="p">[[</span><span class="n">packages</span><span class="p">]]</span>
|
|
<span class="n">name</span> <span class="o">=</span> <span class="s">"bash"</span>
|
|
<span class="n">version</span> <span class="o">=</span> <span class="s">"4.4.*"</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The <tt class="docutils literal"><span class="pre">name</span></tt> field is the name of the blueprint. It can contain spaces, but they will be converted to <tt class="docutils literal"><span class="pre">-</span></tt>
|
|
when it is written to disk. It should be short and descriptive.</p>
|
|
<p><tt class="docutils literal"><span class="pre">description</span></tt> can be a longer description of the blueprint, it is only used for display purposes.</p>
|
|
<p><tt class="docutils literal"><span class="pre">version</span></tt> is a <a class="reference external" href="https://semver.org/">semver compatible</a> version number. If
|
|
a new blueprint is uploaded with the same <tt class="docutils literal"><span class="pre">version</span></tt> the server will
|
|
automatically bump the PATCH level of the <tt class="docutils literal"><span class="pre">version</span></tt>. If the <tt class="docutils literal"><span class="pre">version</span></tt>
|
|
doesn’t match it will be used as is. eg. Uploading a blueprint with <tt class="docutils literal"><span class="pre">version</span></tt>
|
|
set to <tt class="docutils literal"><span class="pre">0.1.0</span></tt> when the existing blueprint <tt class="docutils literal"><span class="pre">version</span></tt> is <tt class="docutils literal"><span class="pre">0.0.1</span></tt> will
|
|
result in the new blueprint being stored as <tt class="docutils literal"><span class="pre">version</span> <span class="pre">0.1.0</span></tt>.</p>
|
|
<div class="section" id="packages-and-modules">
|
|
<h3>[[packages]] and [[modules]]<a class="headerlink" href="#packages-and-modules" title="Permalink to this headline">¶</a></h3>
|
|
<p>These entries describe the package names and matching version glob to be installed into the image.</p>
|
|
<p>The names must match the names exactly, and the versions can be an exact match
|
|
or a filesystem-like glob of the version using <tt class="docutils literal"><span class="pre">*</span></tt> wildcards and <tt class="docutils literal"><span class="pre">?</span></tt>
|
|
character matching.</p>
|
|
<p>NOTE: As of lorax-composer-29.2-1 the versions are not used for depsolving,
|
|
that is planned for a future release. And currently there are no differences
|
|
between <tt class="docutils literal"><span class="pre">packages</span></tt> and <tt class="docutils literal"><span class="pre">modules</span></tt> in <tt class="docutils literal"><span class="pre">lorax-composer</span></tt>.</p>
|
|
</div>
|
|
<div class="section" id="groups">
|
|
<h3>[[groups]]<a class="headerlink" href="#groups" title="Permalink to this headline">¶</a></h3>
|
|
<p>These entries describe a group of packages to be installed into the image. Package groups are
|
|
defined in the repository metadata. Each group has a descriptive name used primarily for display
|
|
in user interfaces and an ID more commonly used in kickstart files. Here, the ID is the expected
|
|
way of listing a group.</p>
|
|
<p>Groups have three different ways of categorizing their packages: mandatory, default, and optional.
|
|
For purposes of blueprints, mandatory and default packages will be installed. There is no mechanism
|
|
for selecting optional packages.</p>
|
|
</div>
|
|
<div class="section" id="customizations">
|
|
<h3>Customizations<a class="headerlink" href="#customizations" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <tt class="docutils literal"><span class="pre">[[customizations]]</span></tt> section can be used to configure the hostname of the final image. eg.:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="p">[[</span><span class="n">customizations</span><span class="p">]]</span>
|
|
<span class="n">hostname</span> <span class="o">=</span> <span class="s">"baseimage"</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="section" id="customizations-sshkey">
|
|
<h4>[[customizations.sshkey]]<a class="headerlink" href="#customizations-sshkey" title="Permalink to this headline">¶</a></h4>
|
|
<p>Set an existing user’s ssh key in the final image:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="p">[[</span><span class="n">customizations</span><span class="o">.</span><span class="n">sshkey</span><span class="p">]]</span>
|
|
<span class="n">user</span> <span class="o">=</span> <span class="s">"root"</span>
|
|
<span class="n">key</span> <span class="o">=</span> <span class="s">"PUBLIC SSH KEY"</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The key will be added to the user’s authorized_keys file.</p>
|
|
</div>
|
|
<div class="section" id="customizations-user">
|
|
<h4>[[customizations.user]]<a class="headerlink" href="#customizations-user" title="Permalink to this headline">¶</a></h4>
|
|
<p>Add a user to the image, and/or set their ssh key.
|
|
All fields for this section are optional except for the <tt class="docutils literal"><span class="pre">name</span></tt>, here is a complete example:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="p">[[</span><span class="n">customizations</span><span class="o">.</span><span class="n">user</span><span class="p">]]</span>
|
|
<span class="n">name</span> <span class="o">=</span> <span class="s">"admin"</span>
|
|
<span class="n">description</span> <span class="o">=</span> <span class="s">"Administrator account"</span>
|
|
<span class="n">password</span> <span class="o">=</span> <span class="s">"$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31L..."</span>
|
|
<span class="n">key</span> <span class="o">=</span> <span class="s">"PUBLIC SSH KEY"</span>
|
|
<span class="n">home</span> <span class="o">=</span> <span class="s">"/srv/widget/"</span>
|
|
<span class="n">shell</span> <span class="o">=</span> <span class="s">"/usr/bin/bash"</span>
|
|
<span class="n">groups</span> <span class="o">=</span> <span class="p">[</span><span class="s">"widget"</span><span class="p">,</span> <span class="s">"users"</span><span class="p">,</span> <span class="s">"wheel"</span><span class="p">]</span>
|
|
<span class="n">uid</span> <span class="o">=</span> <span class="mi">1200</span>
|
|
<span class="n">gid</span> <span class="o">=</span> <span class="mi">1200</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>If the password starts with <tt class="docutils literal"><span class="pre">$6$</span></tt>, <tt class="docutils literal"><span class="pre">$5$</span></tt>, or <tt class="docutils literal"><span class="pre">$2b$</span></tt> it will be stored as
|
|
an encrypted password. Otherwise it will be treated as a plain text password.</p>
|
|
</div>
|
|
<div class="section" id="customizations-group">
|
|
<h4>[[customizations.group]]<a class="headerlink" href="#customizations-group" title="Permalink to this headline">¶</a></h4>
|
|
<p>Add a group to the image. <tt class="docutils literal"><span class="pre">name</span></tt> is required and <tt class="docutils literal"><span class="pre">gid</span></tt> is optional:</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="p">[[</span><span class="n">customizations</span><span class="o">.</span><span class="n">group</span><span class="p">]]</span>
|
|
<span class="n">name</span> <span class="o">=</span> <span class="s">"widget"</span>
|
|
<span class="n">gid</span> <span class="o">=</span> <span class="mi">1130</span>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="adding-output-types">
|
|
<h2>Adding Output Types<a class="headerlink" href="#adding-output-types" title="Permalink to this headline">¶</a></h2>
|
|
<p><tt class="docutils literal"><span class="pre">livemedia-creator</span></tt> supports a large number of output types, and only some of
|
|
these are currently available via <tt class="docutils literal"><span class="pre">lorax-composer</span></tt>. To add a new output type to
|
|
lorax-composer a kickstart file needs to be added to <tt class="docutils literal"><span class="pre">./share/composer/</span></tt>. The
|
|
name of the kickstart is what will be used by the <tt class="docutils literal"><span class="pre">/compose/types</span></tt> route, and the
|
|
<tt class="docutils literal"><span class="pre">compose_type</span></tt> field of the POST to start a compose. It also needs to have
|
|
code added to the <a class="reference internal" href="pylorax.api.html#pylorax.api.compose.compose_args" title="pylorax.api.compose.compose_args"><tt class="xref py py-func docutils literal"><span class="pre">pylorax.api.compose.compose_args()</span></tt></a> function. The
|
|
<tt class="docutils literal"><span class="pre">_MAP</span></tt> entry in this function defines what lorax-composer will pass to
|
|
<a class="reference internal" href="pylorax.html#pylorax.installer.novirt_install" title="pylorax.installer.novirt_install"><tt class="xref py py-func docutils literal"><span class="pre">pylorax.installer.novirt_install()</span></tt></a> when it runs the compose. When the
|
|
compose is finished the output files need to be copied out of the build
|
|
directory (<tt class="docutils literal"><span class="pre">/var/lib/lorax/composer/results/<UUID>/compose/</span></tt>),
|
|
<a class="reference internal" href="pylorax.api.html#pylorax.api.compose.move_compose_results" title="pylorax.api.compose.move_compose_results"><tt class="xref py py-func docutils literal"><span class="pre">pylorax.api.compose.move_compose_results()</span></tt></a> handles this for each type.
|
|
You should move them instead of copying to save space.</p>
|
|
<p>If the new output type does not have support in livemedia-creator it should be
|
|
added there first. This will make the output available to the widest number of
|
|
users.</p>
|
|
<div class="section" id="example-add-partitioned-disk-support">
|
|
<h3>Example: Add partitioned disk support<a class="headerlink" href="#example-add-partitioned-disk-support" title="Permalink to this headline">¶</a></h3>
|
|
<p>Partitioned disk support is something that livemedia-creator already supports
|
|
via the <tt class="docutils literal"><span class="pre">--make-disk</span></tt> cmdline argument. To add this to lorax-composer it
|
|
needs 3 things:</p>
|
|
<ul class="simple">
|
|
<li>A <tt class="docutils literal"><span class="pre">partitioned-disk.ks</span></tt> file in <tt class="docutils literal"><span class="pre">./share/composer/</span></tt></li>
|
|
<li>A new entry in the _MAP in <a class="reference internal" href="pylorax.api.html#pylorax.api.compose.compose_args" title="pylorax.api.compose.compose_args"><tt class="xref py py-func docutils literal"><span class="pre">pylorax.api.compose.compose_args()</span></tt></a></li>
|
|
<li>Add a bit of code to <a class="reference internal" href="pylorax.api.html#pylorax.api.compose.move_compose_results" title="pylorax.api.compose.move_compose_results"><tt class="xref py py-func docutils literal"><span class="pre">pylorax.api.compose.move_compose_results()</span></tt></a> to move the disk image from
|
|
the compose directory to the results directory.</li>
|
|
</ul>
|
|
<p>The <tt class="docutils literal"><span class="pre">partitioned-disk.ks</span></tt> is pretty similar to the example minimal kickstart
|
|
in <tt class="docutils literal"><span class="pre">./docs/rhel7-minimal.ks</span></tt>. You should remove the <tt class="docutils literal"><span class="pre">url</span></tt> and <tt class="docutils literal"><span class="pre">repo</span></tt>
|
|
commands, they will be added by the compose process. Make sure the bootloader
|
|
packages are included in the <tt class="docutils literal"><span class="pre">%packages</span></tt> section at the end of the kickstart,
|
|
and you will want to leave off the <tt class="docutils literal"><span class="pre">%end</span></tt> so that the compose can append the
|
|
list of packages from the blueprint.</p>
|
|
<p>The new <tt class="docutils literal"><span class="pre">_MAP</span></tt> entry should be a copy of one of the existing entries, but with <tt class="docutils literal"><span class="pre">make_disk</span></tt> set
|
|
to <tt class="docutils literal"><span class="pre">True</span></tt>. Make sure that none of the other <tt class="docutils literal"><span class="pre">make_*</span></tt> options are <tt class="docutils literal"><span class="pre">True</span></tt>. The <tt class="docutils literal"><span class="pre">image_name</span></tt> is
|
|
what the name of the final image will be.</p>
|
|
<p><tt class="docutils literal"><span class="pre">move_compose_results()</span></tt> can be as simple as moving the output file into
|
|
the results directory, or it could do some post-processing on it. The end of
|
|
the function should always clean up the <tt class="docutils literal"><span class="pre">./compose/</span></tt> directory, removing any
|
|
unneeded extra files. This is especially true for the <tt class="docutils literal"><span class="pre">live-iso</span></tt> since it produces
|
|
the contents of the iso as well as the boot.iso itself.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="package-sources">
|
|
<h2>Package Sources<a class="headerlink" href="#package-sources" title="Permalink to this headline">¶</a></h2>
|
|
<p>By default lorax-composer uses the host’s configured repositories. It copies
|
|
the <tt class="docutils literal"><span class="pre">*.repo</span></tt> files from <tt class="docutils literal"><span class="pre">/etc/yum.repos.d/</span></tt> into
|
|
<tt class="docutils literal"><span class="pre">/var/lib/lorax/composer/repos.d/</span></tt> at startup, these are immutable system
|
|
repositories and cannot be deleted or changed. If you want to add additional
|
|
repos you can put them into <tt class="docutils literal"><span class="pre">/var/lib/lorax/composer/repos.d/</span></tt> or use the
|
|
<tt class="docutils literal"><span class="pre">/api/v0/projects/source/*</span></tt> API routes to create them.</p>
|
|
<p>The new source can be added by doing a POST to the <tt class="docutils literal"><span class="pre">/api/v0/projects/source/new</span></tt>
|
|
route using JSON (with <cite>Content-Type</cite> header set to <cite>application/json</cite>) or TOML
|
|
(with it set to <cite>text/x-toml</cite>). The format of the source looks like this (in
|
|
TOML):</p>
|
|
<div class="highlight-python"><div class="highlight"><pre><span class="n">name</span> <span class="o">=</span> <span class="s">"custom-source-1"</span>
|
|
<span class="n">url</span> <span class="o">=</span> <span class="s">"https://url/path/to/repository/"</span>
|
|
<span class="nb">type</span> <span class="o">=</span> <span class="s">"yum-baseurl"</span>
|
|
<span class="n">proxy</span> <span class="o">=</span> <span class="s">"https://proxy-url/"</span>
|
|
<span class="n">check_ssl</span> <span class="o">=</span> <span class="n">true</span>
|
|
<span class="n">check_gpg</span> <span class="o">=</span> <span class="n">true</span>
|
|
<span class="n">gpgkey_urls</span> <span class="o">=</span> <span class="p">[</span><span class="s">"https://url/path/to/gpg-key"</span><span class="p">]</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The <tt class="docutils literal"><span class="pre">proxy</span></tt> and <tt class="docutils literal"><span class="pre">gpgkey_urls</span></tt> entries are optional. All of the others are required. The supported
|
|
types for the urls are:</p>
|
|
<ul class="simple">
|
|
<li><tt class="docutils literal"><span class="pre">yum-baseurl</span></tt> is a URL to a yum repository.</li>
|
|
<li><tt class="docutils literal"><span class="pre">yum-mirrorlist</span></tt> is a URL for a mirrorlist.</li>
|
|
<li><tt class="docutils literal"><span class="pre">yum-metalink</span></tt> is a URL for a metalink.</li>
|
|
</ul>
|
|
<p>If <tt class="docutils literal"><span class="pre">check_ssl</span></tt> is true the https certificates must be valid. If they are self-signed you can either set
|
|
this to false, or add your Certificate Authority to the host system.</p>
|
|
<p>If <tt class="docutils literal"><span class="pre">check_gpg</span></tt> is true the GPG key must either be installed on the host system, or <tt class="docutils literal"><span class="pre">gpgkey_urls</span></tt>
|
|
should point to it.</p>
|
|
<p>You can edit an existing source (other than system sources), by doing a POST to the <tt class="docutils literal"><span class="pre">new</span></tt> route
|
|
with the new version of the source. It will overwrite the previous one.</p>
|
|
<p>A list of existing sources is available from <tt class="docutils literal"><span class="pre">/api/v0/projects/source/list</span></tt>, and detailed info
|
|
on a source can be retrieved with the <tt class="docutils literal"><span class="pre">/api/v0/projects/source/info/<source-name></span></tt> route. By default
|
|
it returns JSON but it can also return TOML if <tt class="docutils literal"><span class="pre">?format=toml</span></tt> is added to the request.</p>
|
|
<p>Non-system sources can be deleted by doing a <tt class="docutils literal"><span class="pre">DELETE</span></tt> request to the
|
|
<tt class="docutils literal"><span class="pre">/api/v0/projects/source/delete/<source-name></span></tt> route.</p>
|
|
<p>The documentation for the source API routes can be <a class="reference external" href="pylorax.api.html#api-v0-projects-source-list">found here</a></p>
|
|
<p>The configured sources are used for all blueprint depsolve operations, and for composing images.
|
|
When adding additional sources you must make sure that the packages in the source do not
|
|
conflict with any other package sources, otherwise depsolving will fail.</p>
|
|
<div class="section" id="dvd-iso-package-source">
|
|
<h3>DVD ISO Package Source<a class="headerlink" href="#dvd-iso-package-source" title="Permalink to this headline">¶</a></h3>
|
|
<p>In some situations the system may want to <em>only</em> use a DVD iso as the package
|
|
source, not the repos from the network. <tt class="docutils literal"><span class="pre">lorax-composer</span></tt> and <tt class="docutils literal"><span class="pre">anaconda</span></tt>
|
|
understand <tt class="docutils literal"><span class="pre">file://</span></tt> URLs so you can mount an iso on the host, and replace the
|
|
system repo files with a configuration file pointing to the DVD.</p>
|
|
<ul>
|
|
<li><p class="first">Stop the <tt class="docutils literal"><span class="pre">lorax-composer.service</span></tt> if it is running</p>
|
|
</li>
|
|
<li><p class="first">Move the repo files in <tt class="docutils literal"><span class="pre">/etc/yum.repos.d/</span></tt> someplace safe</p>
|
|
</li>
|
|
<li><p class="first">Create a new <tt class="docutils literal"><span class="pre">iso.repo</span></tt> file in <tt class="docutils literal"><span class="pre">/etc/yum.repos.d/</span></tt>:</p>
|
|
<div class="highlight-python"><pre>[iso]
|
|
name=iso
|
|
baseurl=file:///mnt/iso/
|
|
enabled=1
|
|
gpgcheck=1
|
|
gpgkey=file:///mnt/iso/RPM-GPG-KEY-redhat-release</pre>
|
|
</div>
|
|
</li>
|
|
<li><p class="first">Remove all the cached repo files from <tt class="docutils literal"><span class="pre">/var/lib/lorax/composer/repos/</span></tt></p>
|
|
</li>
|
|
<li><p class="first">Restart the <tt class="docutils literal"><span class="pre">lorax-composer.service</span></tt></p>
|
|
</li>
|
|
<li><p class="first">Check the output of <tt class="docutils literal"><span class="pre">composer-cli</span> <span class="pre">status</span> <span class="pre">show</span></tt> for any output specific depsolve errors.
|
|
For example, the DVD usually does not include <tt class="docutils literal"><span class="pre">grub2-efi-*-cdboot-*</span></tt> so the live-iso image
|
|
type will not be available.</p>
|
|
</li>
|
|
</ul>
|
|
<p>If you want to <em>add</em> the DVD source to the existing sources you can do that by
|
|
mounting the iso and creating a source file to point to it as described in the
|
|
<a class="reference internal" href="#package-sources">Package Sources</a> documentation. In that case there is no need to remove the other
|
|
sources from <tt class="docutils literal"><span class="pre">/etc/yum.repos.d/</span></tt> or clear the cached repos.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="sphinxsidebar">
|
|
<div class="sphinxsidebarwrapper">
|
|
<h3><a href="index.html">Table Of Contents</a></h3>
|
|
<ul>
|
|
<li><a class="reference internal" href="#">lorax-composer</a><ul>
|
|
<li><a class="reference internal" href="#important-things-to-note">Important Things To Note</a></li>
|
|
<li><a class="reference internal" href="#installation">Installation</a></li>
|
|
<li><a class="reference internal" href="#quickstart">Quickstart</a></li>
|
|
<li><a class="reference internal" href="#logs">Logs</a></li>
|
|
<li><a class="reference internal" href="#security">Security</a></li>
|
|
<li><a class="reference internal" href="#how-it-works">How it Works</a></li>
|
|
<li><a class="reference internal" href="#composing-images">Composing Images</a></li>
|
|
<li><a class="reference internal" href="#blueprints">Blueprints</a><ul>
|
|
<li><a class="reference internal" href="#packages-and-modules">[[packages]] and [[modules]]</a></li>
|
|
<li><a class="reference internal" href="#groups">[[groups]]</a></li>
|
|
<li><a class="reference internal" href="#customizations">Customizations</a><ul>
|
|
<li><a class="reference internal" href="#customizations-sshkey">[[customizations.sshkey]]</a></li>
|
|
<li><a class="reference internal" href="#customizations-user">[[customizations.user]]</a></li>
|
|
<li><a class="reference internal" href="#customizations-group">[[customizations.group]]</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#adding-output-types">Adding Output Types</a><ul>
|
|
<li><a class="reference internal" href="#example-add-partitioned-disk-support">Example: Add partitioned disk support</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#package-sources">Package Sources</a><ul>
|
|
<li><a class="reference internal" href="#dvd-iso-package-source">DVD ISO Package Source</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<h4>Previous topic</h4>
|
|
<p class="topless"><a href="livemedia-creator.html"
|
|
title="previous chapter">livemedia-creator</a></p>
|
|
<h4>Next topic</h4>
|
|
<p class="topless"><a href="composer-cli.html"
|
|
title="next chapter">composer-cli</a></p>
|
|
<h3>This Page</h3>
|
|
<ul class="this-page-menu">
|
|
<li><a href="_sources/lorax-composer.txt"
|
|
rel="nofollow">Show Source</a></li>
|
|
</ul>
|
|
<div id="searchbox" style="display: none">
|
|
<h3>Quick search</h3>
|
|
<form class="search" action="search.html" method="get">
|
|
<input type="text" name="q" />
|
|
<input type="submit" value="Go" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
<p class="searchtip" style="font-size: 90%">
|
|
Enter search terms or a module, class or function name.
|
|
</p>
|
|
</div>
|
|
<script type="text/javascript">$('#searchbox').show(0);</script>
|
|
</div>
|
|
</div>
|
|
<div class="clearer"></div>
|
|
</div>
|
|
<div class="related">
|
|
<h3>Navigation</h3>
|
|
<ul>
|
|
<li class="right" style="margin-right: 10px">
|
|
<a href="genindex.html" title="General Index"
|
|
>index</a></li>
|
|
<li class="right" >
|
|
<a href="py-modindex.html" title="Python Module Index"
|
|
>modules</a> |</li>
|
|
<li class="right" >
|
|
<a href="composer-cli.html" title="composer-cli"
|
|
>next</a> |</li>
|
|
<li class="right" >
|
|
<a href="livemedia-creator.html" title="livemedia-creator"
|
|
>previous</a> |</li>
|
|
<li><a href="index.html">Lorax 19.7.22 documentation</a> »</li>
|
|
</ul>
|
|
</div>
|
|
<div class="footer">
|
|
© Copyright 2018, Red Hat, Inc..
|
|
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.1.3.
|
|
</div>
|
|
</body>
|
|
</html> |