771 lines
59 KiB
HTML
771 lines
59 KiB
HTML
|
|
|
|
<!DOCTYPE html>
|
|
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
|
|
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
|
|
<head>
|
|
<meta charset="utf-8">
|
|
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
|
|
<title>lorax-composer — Lorax 32.1 documentation</title>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<script type="text/javascript" src="_static/js/modernizr.min.js"></script>
|
|
|
|
|
|
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></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>
|
|
<script type="text/javascript" src="_static/language_data.js"></script>
|
|
|
|
<script type="text/javascript" src="_static/js/theme.js"></script>
|
|
|
|
|
|
|
|
|
|
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
|
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
|
<link rel="index" title="Index" href="genindex.html" />
|
|
<link rel="search" title="Search" href="search.html" />
|
|
<link rel="next" title="composer-cli" href="composer-cli.html" />
|
|
<link rel="prev" title="livemedia-creator" href="livemedia-creator.html" />
|
|
</head>
|
|
|
|
<body class="wy-body-for-nav">
|
|
|
|
|
|
<div class="wy-grid-for-nav">
|
|
|
|
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
|
<div class="wy-side-scroll">
|
|
<div class="wy-side-nav-search" >
|
|
|
|
|
|
|
|
<a href="index.html" class="icon icon-home"> Lorax
|
|
|
|
|
|
|
|
</a>
|
|
|
|
|
|
|
|
|
|
<div class="version">
|
|
32.1
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div role="search">
|
|
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
|
<input type="text" name="q" placeholder="Search docs" />
|
|
<input type="hidden" name="check_keywords" value="yes" />
|
|
<input type="hidden" name="area" value="default" />
|
|
</form>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<ul class="current">
|
|
<li class="toctree-l1"><a class="reference internal" href="intro.html">Introduction to Lorax</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="intro.html#before-lorax">Before Lorax</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="lorax.html">Lorax</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="livemedia-creator.html">livemedia-creator</a></li>
|
|
<li class="toctree-l1 current"><a class="current reference internal" href="#">lorax-composer</a><ul>
|
|
<li class="toctree-l2"><a class="reference internal" href="#important-things-to-note">Important Things To Note</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#installation">Installation</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#quickstart">Quickstart</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#logs">Logs</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#security">Security</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#lorax-composer-cmdline-arguments">lorax-composer cmdline arguments</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#Positional Arguments">Positional Arguments</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#Named Arguments">Named Arguments</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#how-it-works">How it Works</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#composing-images">Composing Images</a></li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#blueprints">Blueprints</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#packages-and-modules">[[packages]] and [[modules]]</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#groups">[[groups]]</a></li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#customizations">Customizations</a><ul>
|
|
<li class="toctree-l4"><a class="reference internal" href="#customizations-kernel">[customizations.kernel]</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="#customizations-sshkey">[[customizations.sshkey]]</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="#customizations-user">[[customizations.user]]</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="#customizations-group">[[customizations.group]]</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="#customizations-timezone">[customizations.timezone]</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="#customizations-locale">[customizations.locale]</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="#customizations-firewall">[customizations.firewall]</a></li>
|
|
<li class="toctree-l4"><a class="reference internal" href="#customizations-services">[customizations.services]</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l3"><a class="reference internal" href="#repos-git">[[repos.git]]</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#adding-output-types">Adding Output Types</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#example-add-partitioned-disk-support">Example: Add partitioned disk support</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l2"><a class="reference internal" href="#package-sources">Package Sources</a><ul>
|
|
<li class="toctree-l3"><a class="reference internal" href="#dvd-iso-package-source">DVD ISO Package Source</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
<li class="toctree-l1"><a class="reference internal" href="composer-cli.html">composer-cli</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="product-images.html">Product and Updates Images</a></li>
|
|
<li class="toctree-l1"><a class="reference internal" href="modules.html">src</a></li>
|
|
</ul>
|
|
|
|
|
|
|
|
</div>
|
|
</div>
|
|
</nav>
|
|
|
|
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
|
|
|
|
|
<nav class="wy-nav-top" aria-label="top navigation">
|
|
|
|
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
|
<a href="index.html">Lorax</a>
|
|
|
|
</nav>
|
|
|
|
|
|
<div class="wy-nav-content">
|
|
|
|
<div class="rst-content">
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<div role="navigation" aria-label="breadcrumbs navigation">
|
|
|
|
<ul class="wy-breadcrumbs">
|
|
|
|
<li><a href="index.html">Docs</a> »</li>
|
|
|
|
<li>lorax-composer</li>
|
|
|
|
|
|
<li class="wy-breadcrumbs-aside">
|
|
|
|
|
|
<a href="_sources/lorax-composer.rst.txt" rel="nofollow"> View page source</a>
|
|
|
|
|
|
</li>
|
|
|
|
</ul>
|
|
|
|
|
|
<hr/>
|
|
</div>
|
|
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
|
<div itemprop="articleBody">
|
|
|
|
<div class="section" id="lorax-composer">
|
|
<h1>lorax-composer<a class="headerlink" href="#lorax-composer" title="Permalink to this headline">¶</a></h1>
|
|
<dl class="field-list simple">
|
|
<dt class="field-odd">Authors</dt>
|
|
<dd class="field-odd"><p>Brian C. Lane <<a class="reference external" href="mailto:bcl%40redhat.com">bcl<span>@</span>redhat<span>.</span>com</a>></p>
|
|
</dd>
|
|
</dl>
|
|
<p><code class="docutils literal notranslate"><span class="pre">lorax-composer</span></code> 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><p>As of version 30.7 SELinux can be set to Enforcing. The current state is
|
|
logged for debugging purposes and if there are SELinux denials they should
|
|
be reported as a bug.</p></li>
|
|
<li><p>All image types lock the root account, except for live-iso. You will need to either
|
|
use one of the <a class="reference internal" href="#customizations">Customizations</a> methods for setting a ssh key/password, install a
|
|
package that creates a user, or use something like <cite>cloud-init</cite> to setup access at
|
|
boot time.</p></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 <code class="docutils literal notranslate"><span class="pre">lorax-composer</span></code> is to use <code class="docutils literal notranslate"><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></code>, this will setup the weldr user and install the
|
|
systemd socket activation service. You will then need to enable it with <code class="docutils literal notranslate"><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></code>. 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="admonition-title">Note</p>
|
|
<p>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><p>Create a <code class="docutils literal notranslate"><span class="pre">weldr</span></code> user and group by running <code class="docutils literal notranslate"><span class="pre">useradd</span> <span class="pre">weldr</span></code></p></li>
|
|
<li><p>Remove any pre-existing socket directory with <code class="docutils literal notranslate"><span class="pre">rm</span> <span class="pre">-rf</span> <span class="pre">/run/weldr/</span></code>
|
|
A new directory with correct permissions will be created the first time the server runs.</p></li>
|
|
<li><p>Enable the socket activation with <code class="docutils literal notranslate"><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></code>.</p></li>
|
|
</ol>
|
|
<p>NOTE: You can also run it directly with <code class="docutils literal notranslate"><span class="pre">lorax-composer</span> <span class="pre">/path/to/blueprints</span></code>. However,
|
|
<code class="docutils literal notranslate"><span class="pre">lorax-composer</span></code> 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 <code class="docutils literal notranslate"><span class="pre">/path/to/blueprints/</span></code> directory is where the blueprints' git repo will
|
|
be created, and all the blueprints created with the <code class="docutils literal notranslate"><span class="pre">/api/v0/blueprints/new</span></code>
|
|
route will be stored. If there are blueprint <code class="docutils literal notranslate"><span class="pre">.toml</span></code> files in the top level
|
|
of the directory they will be imported into the blueprint git storage when
|
|
<code class="docutils literal notranslate"><span class="pre">lorax-composer</span></code> 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 <code class="docutils literal notranslate"><span class="pre">/var/log/lorax-composer/</span></code> 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 <code class="docutils literal notranslate"><span class="pre">lorax-composer</span></code>:</p>
|
|
<ul class="simple">
|
|
<li><p>One of the API server threads needs to retain root privileges in order to run Anaconda.</p></li>
|
|
<li><p>Only allow authorized users access to the <code class="docutils literal notranslate"><span class="pre">weldr</span></code> group and socket.</p></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 <code class="docutils literal notranslate"><span class="pre">lorax-composer</span></code>.</p>
|
|
</div>
|
|
<div class="section" id="lorax-composer-cmdline-arguments">
|
|
<h2>lorax-composer cmdline arguments<a class="headerlink" href="#lorax-composer-cmdline-arguments" title="Permalink to this headline">¶</a></h2>
|
|
<p><p>Lorax Composer API Server</p>
|
|
</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">usage</span><span class="p">:</span> <span class="n">lorax</span><span class="o">-</span><span class="n">composer</span> <span class="p">[</span><span class="o">-</span><span class="n">h</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">socket</span> <span class="n">SOCKET</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">user</span> <span class="n">USER</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">group</span> <span class="n">GROUP</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">log</span> <span class="n">LOG</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">mockfiles</span> <span class="n">MOCKFILES</span><span class="p">]</span>
|
|
<span class="p">[</span><span class="o">--</span><span class="n">sharedir</span> <span class="n">SHAREDIR</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">V</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">c</span> <span class="n">CONFIG</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">releasever</span> <span class="n">STRING</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">tmp</span> <span class="n">TMP</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">proxy</span> <span class="n">PROXY</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">system</span><span class="o">-</span><span class="n">repos</span><span class="p">]</span>
|
|
<span class="n">BLUEPRINTS</span>
|
|
</pre></div>
|
|
</div>
|
|
<div class="section" id="Positional Arguments">
|
|
<h3>Positional Arguments<a class="headerlink" href="#Positional Arguments" title="Permalink to this headline">¶</a></h3>
|
|
<dl class="option-list">
|
|
<dt><kbd>BLUEPRINTS</kbd></dt>
|
|
<dd><p>Path to the blueprints</p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<div class="section" id="Named Arguments">
|
|
<h3>Named Arguments<a class="headerlink" href="#Named Arguments" title="Permalink to this headline">¶</a></h3>
|
|
<dl class="option-list">
|
|
<dt><kbd>--socket</kbd></dt>
|
|
<dd><p>Path to the socket file to listen on</p>
|
|
<p>Default: "/run/weldr/api.socket"</p>
|
|
</dd>
|
|
<dt><kbd>--user</kbd></dt>
|
|
<dd><p>User to use for reduced permissions</p>
|
|
<p>Default: "root"</p>
|
|
</dd>
|
|
<dt><kbd>--group</kbd></dt>
|
|
<dd><p>Group to set ownership of the socket to</p>
|
|
<p>Default: "weldr"</p>
|
|
</dd>
|
|
<dt><kbd>--log</kbd></dt>
|
|
<dd><p>Path to logfile (/var/log/lorax-composer/composer.log)</p>
|
|
<p>Default: "/var/log/lorax-composer/composer.log"</p>
|
|
</dd>
|
|
<dt><kbd>--mockfiles</kbd></dt>
|
|
<dd><p>Path to JSON files used for /api/mock/ paths (/var/tmp/bdcs-mockfiles/)</p>
|
|
<p>Default: "/var/tmp/bdcs-mockfiles/"</p>
|
|
</dd>
|
|
<dt><kbd>--sharedir</kbd></dt>
|
|
<dd><p>Directory containing all the templates. Overrides config file sharedir</p>
|
|
</dd>
|
|
<dt><kbd>-V</kbd></dt>
|
|
<dd><p>show program's version number and exit</p>
|
|
<p>Default: False</p>
|
|
</dd>
|
|
<dt><kbd>-c, --config</kbd></dt>
|
|
<dd><p>Path to lorax-composer configuration file.</p>
|
|
<p>Default: "/etc/lorax/composer.conf"</p>
|
|
</dd>
|
|
<dt><kbd>--releasever</kbd></dt>
|
|
<dd><p>Release version to use for $releasever in dnf repository urls</p>
|
|
</dd>
|
|
<dt><kbd>--tmp</kbd></dt>
|
|
<dd><p>Top level temporary directory</p>
|
|
<p>Default: "/var/tmp"</p>
|
|
</dd>
|
|
<dt><kbd>--proxy</kbd></dt>
|
|
<dd><p>Set proxy for DNF, overrides configuration file setting.</p>
|
|
</dd>
|
|
<dt><kbd>--no-system-repos</kbd></dt>
|
|
<dd><p>Do not copy over system repos from /etc/yum.repos.d/ at startup</p>
|
|
<p>Default: False</p>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
</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 <code class="docutils literal notranslate"><span class="pre">weldr</span></code>. Communication with it is via a unix
|
|
domain socket (<code class="docutils literal notranslate"><span class="pre">/run/weldr/api.socket</span></code> by default). The directory and socket
|
|
are owned by <code class="docutils literal notranslate"><span class="pre">root:weldr</span></code> so that any user in the <code class="docutils literal notranslate"><span class="pre">weldr</span></code> group can use the API
|
|
to control <code class="docutils literal notranslate"><span class="pre">lorax-composer</span></code>.</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 <code class="docutils literal notranslate"><span class="pre">--socket</span></code> and <code class="docutils literal notranslate"><span class="pre">--group</span></code> arguments.</p>
|
|
<p>It will then drop root privileges for the API thread and run as the <code class="docutils literal notranslate"><span class="pre">weldr</span></code>
|
|
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 <code class="docutils literal notranslate"><span class="pre">lorax-composer</span></code> <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-default notranslate"><div class="highlight"><pre><span></span><span class="n">name</span> <span class="o">=</span> <span class="s2">"base"</span>
|
|
<span class="n">description</span> <span class="o">=</span> <span class="s2">"A base system with bash"</span>
|
|
<span class="n">version</span> <span class="o">=</span> <span class="s2">"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="s2">"bash"</span>
|
|
<span class="n">version</span> <span class="o">=</span> <span class="s2">"4.4.*"</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">name</span></code> field is the name of the blueprint. It can contain spaces, but they will be converted to <code class="docutils literal notranslate"><span class="pre">-</span></code>
|
|
when it is written to disk. It should be short and descriptive.</p>
|
|
<p><code class="docutils literal notranslate"><span class="pre">description</span></code> can be a longer description of the blueprint, it is only used for display purposes.</p>
|
|
<p><code class="docutils literal notranslate"><span class="pre">version</span></code> is a <a class="reference external" href="https://semver.org/">semver compatible</a> version number. If
|
|
a new blueprint is uploaded with the same <code class="docutils literal notranslate"><span class="pre">version</span></code> the server will
|
|
automatically bump the PATCH level of the <code class="docutils literal notranslate"><span class="pre">version</span></code>. If the <code class="docutils literal notranslate"><span class="pre">version</span></code>
|
|
doesn't match it will be used as is. eg. Uploading a blueprint with <code class="docutils literal notranslate"><span class="pre">version</span></code>
|
|
set to <code class="docutils literal notranslate"><span class="pre">0.1.0</span></code> when the existing blueprint <code class="docutils literal notranslate"><span class="pre">version</span></code> is <code class="docutils literal notranslate"><span class="pre">0.0.1</span></code> will
|
|
result in the new blueprint being stored as <code class="docutils literal notranslate"><span class="pre">version</span> <span class="pre">0.1.0</span></code>.</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 <code class="docutils literal notranslate"><span class="pre">*</span></code> wildcards and <code class="docutils literal notranslate"><span class="pre">?</span></code>
|
|
character matching.</p>
|
|
<p>NOTE: Currently there are no differences between <code class="docutils literal notranslate"><span class="pre">packages</span></code> and <code class="docutils literal notranslate"><span class="pre">modules</span></code>
|
|
in <code class="docutils literal notranslate"><span class="pre">lorax-composer</span></code>. Both are treated like an rpm package dependency.</p>
|
|
<p>For example, to install <code class="docutils literal notranslate"><span class="pre">tmux-2.9a</span></code> and <code class="docutils literal notranslate"><span class="pre">openssh-server-8.*</span></code>, you would add
|
|
this to your blueprint:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></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="s2">"tmux"</span>
|
|
<span class="n">version</span> <span class="o">=</span> <span class="s2">"2.9a"</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="s2">"openssh-server"</span>
|
|
<span class="n">version</span> <span class="o">=</span> <span class="s2">"8.*"</span>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="groups">
|
|
<h3>[[groups]]<a class="headerlink" href="#groups" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">groups</span></code> 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>
|
|
<p>For example, if you want to install the <code class="docutils literal notranslate"><span class="pre">anaconda-tools</span></code> group you would add this to your
|
|
blueprint:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">groups</span><span class="p">]]</span>
|
|
<span class="n">name</span><span class="o">=</span><span class="s2">"anaconda-tools"</span>
|
|
</pre></div>
|
|
</div>
|
|
<p><code class="docutils literal notranslate"><span class="pre">groups</span></code> is a TOML list, so each group needs to be listed separately, like <code class="docutils literal notranslate"><span class="pre">packages</span></code> but with
|
|
no version number.</p>
|
|
</div>
|
|
<div class="section" id="customizations">
|
|
<h3>Customizations<a class="headerlink" href="#customizations" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">[customizations]</span></code> section can be used to configure the hostname of the final image. eg.:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">customizations</span><span class="p">]</span>
|
|
<span class="n">hostname</span> <span class="o">=</span> <span class="s2">"baseimage"</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>This is optional and may be left out to use the defaults.</p>
|
|
<div class="section" id="customizations-kernel">
|
|
<h4>[customizations.kernel]<a class="headerlink" href="#customizations-kernel" title="Permalink to this headline">¶</a></h4>
|
|
<p>This allows you to append arguments to the bootloader's kernel commandline. This will not have any
|
|
effect on <code class="docutils literal notranslate"><span class="pre">tar</span></code> or <code class="docutils literal notranslate"><span class="pre">ext4-filesystem</span></code> images since they do not include a bootloader.</p>
|
|
<p>For example:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">customizations</span><span class="o">.</span><span class="n">kernel</span><span class="p">]</span>
|
|
<span class="n">append</span> <span class="o">=</span> <span class="s2">"nosmt=force"</span>
|
|
</pre></div>
|
|
</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-default notranslate"><div class="highlight"><pre><span></span><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="s2">"root"</span>
|
|
<span class="n">key</span> <span class="o">=</span> <span class="s2">"PUBLIC SSH KEY"</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The key will be added to the user's authorized_keys file.</p>
|
|
<div class="admonition warning">
|
|
<p class="admonition-title">Warning</p>
|
|
<p><code class="docutils literal notranslate"><span class="pre">key</span></code> expects the entire content of <code class="docutils literal notranslate"><span class="pre">~/.ssh/id_rsa.pub</span></code></p>
|
|
</div>
|
|
</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 <code class="docutils literal notranslate"><span class="pre">name</span></code>, here is a complete example:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s2">"admin"</span>
|
|
<span class="n">description</span> <span class="o">=</span> <span class="s2">"Administrator account"</span>
|
|
<span class="n">password</span> <span class="o">=</span> <span class="s2">"$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31L..."</span>
|
|
<span class="n">key</span> <span class="o">=</span> <span class="s2">"PUBLIC SSH KEY"</span>
|
|
<span class="n">home</span> <span class="o">=</span> <span class="s2">"/srv/widget/"</span>
|
|
<span class="n">shell</span> <span class="o">=</span> <span class="s2">"/usr/bin/bash"</span>
|
|
<span class="n">groups</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"widget"</span><span class="p">,</span> <span class="s2">"users"</span><span class="p">,</span> <span class="s2">"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 <code class="docutils literal notranslate"><span class="pre">$6$</span></code>, <code class="docutils literal notranslate"><span class="pre">$5$</span></code>, or <code class="docutils literal notranslate"><span class="pre">$2b$</span></code> it will be stored as
|
|
an encrypted password. Otherwise it will be treated as a plain text password.</p>
|
|
<div class="admonition warning">
|
|
<p class="admonition-title">Warning</p>
|
|
<p><code class="docutils literal notranslate"><span class="pre">key</span></code> expects the entire content of <code class="docutils literal notranslate"><span class="pre">~/.ssh/id_rsa.pub</span></code></p>
|
|
</div>
|
|
</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. <code class="docutils literal notranslate"><span class="pre">name</span></code> is required and <code class="docutils literal notranslate"><span class="pre">gid</span></code> is optional:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><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="s2">"widget"</span>
|
|
<span class="n">gid</span> <span class="o">=</span> <span class="mi">1130</span>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="customizations-timezone">
|
|
<h4>[customizations.timezone]<a class="headerlink" href="#customizations-timezone" title="Permalink to this headline">¶</a></h4>
|
|
<p>Customizing the timezone and the NTP servers to use for the system:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">customizations</span><span class="o">.</span><span class="n">timezone</span><span class="p">]</span>
|
|
<span class="n">timezone</span> <span class="o">=</span> <span class="s2">"US/Eastern"</span>
|
|
<span class="n">ntpservers</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"0.north-america.pool.ntp.org"</span><span class="p">,</span> <span class="s2">"1.north-america.pool.ntp.org"</span><span class="p">]</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The values supported by <code class="docutils literal notranslate"><span class="pre">timezone</span></code> can be listed by running <code class="docutils literal notranslate"><span class="pre">timedatectl</span> <span class="pre">list-timezones</span></code>.</p>
|
|
<p>If no timezone is setup the system will default to using <cite>UTC</cite>. The ntp servers are also
|
|
optional and will default to using the distribution defaults which are fine for most uses.</p>
|
|
<p>In some image types there are already NTP servers setup, eg. Google cloud image, and they
|
|
cannot be overridden because they are required to boot in the selected environment. But the
|
|
timezone will be updated to the one selected in the blueprint.</p>
|
|
</div>
|
|
<div class="section" id="customizations-locale">
|
|
<h4>[customizations.locale]<a class="headerlink" href="#customizations-locale" title="Permalink to this headline">¶</a></h4>
|
|
<p>Customize the locale settings for the system:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">customizations</span><span class="o">.</span><span class="n">locale</span><span class="p">]</span>
|
|
<span class="n">languages</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"en_US.UTF-8"</span><span class="p">]</span>
|
|
<span class="n">keyboard</span> <span class="o">=</span> <span class="s2">"us"</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The values supported by <code class="docutils literal notranslate"><span class="pre">languages</span></code> can be listed by running <code class="docutils literal notranslate"><span class="pre">localectl</span> <span class="pre">list-locales</span></code> from
|
|
the command line.</p>
|
|
<p>The values supported by <code class="docutils literal notranslate"><span class="pre">keyboard</span></code> can be listed by running <code class="docutils literal notranslate"><span class="pre">localectl</span> <span class="pre">list-keymaps</span></code> from
|
|
the command line.</p>
|
|
<p>Multiple languages can be added. The first one becomes the
|
|
primary, and the others are added as secondary. One or the other of <code class="docutils literal notranslate"><span class="pre">languages</span></code>
|
|
or <code class="docutils literal notranslate"><span class="pre">keyboard</span></code> must be included (or both) in the section.</p>
|
|
</div>
|
|
<div class="section" id="customizations-firewall">
|
|
<h4>[customizations.firewall]<a class="headerlink" href="#customizations-firewall" title="Permalink to this headline">¶</a></h4>
|
|
<p>By default the firewall blocks all access except for services that enable their ports explicitly,
|
|
like <code class="docutils literal notranslate"><span class="pre">sshd</span></code>. This command can be used to open other ports or services. Ports are configured using
|
|
the port:protocol format:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">customizations</span><span class="o">.</span><span class="n">firewall</span><span class="p">]</span>
|
|
<span class="n">ports</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"22:tcp"</span><span class="p">,</span> <span class="s2">"80:tcp"</span><span class="p">,</span> <span class="s2">"imap:tcp"</span><span class="p">,</span> <span class="s2">"53:tcp"</span><span class="p">,</span> <span class="s2">"53:udp"</span><span class="p">]</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Numeric ports, or their names from <code class="docutils literal notranslate"><span class="pre">/etc/services</span></code> can be used in the <code class="docutils literal notranslate"><span class="pre">ports</span></code> enabled/disabled lists.</p>
|
|
<p>The blueprint settings extend any existing settings in the image templates, so if <code class="docutils literal notranslate"><span class="pre">sshd</span></code> is
|
|
already enabled it will extend the list of ports with the ones listed by the blueprint.</p>
|
|
<p>If the distribution uses <code class="docutils literal notranslate"><span class="pre">firewalld</span></code> you can specify services listed by <code class="docutils literal notranslate"><span class="pre">firewall-cmd</span> <span class="pre">--get-services</span></code>
|
|
in a <code class="docutils literal notranslate"><span class="pre">customizations.firewall.services</span></code> section:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">customizations</span><span class="o">.</span><span class="n">firewall</span><span class="o">.</span><span class="n">services</span><span class="p">]</span>
|
|
<span class="n">enabled</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"ftp"</span><span class="p">,</span> <span class="s2">"ntp"</span><span class="p">,</span> <span class="s2">"dhcp"</span><span class="p">]</span>
|
|
<span class="n">disabled</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"telnet"</span><span class="p">]</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>Remember that the <code class="docutils literal notranslate"><span class="pre">firewall.services</span></code> are different from the names in <code class="docutils literal notranslate"><span class="pre">/etc/services</span></code>.</p>
|
|
<p>Both are optional, if they are not used leave them out or set them to an empty list <code class="docutils literal notranslate"><span class="pre">[]</span></code>. If you
|
|
only want the default firewall setup this section can be omitted from the blueprint.</p>
|
|
<p>NOTE: The <code class="docutils literal notranslate"><span class="pre">Google</span></code> and <code class="docutils literal notranslate"><span class="pre">OpenStack</span></code> templates explicitly disable the firewall for their environment.
|
|
This cannot be overridden by the blueprint.</p>
|
|
</div>
|
|
<div class="section" id="customizations-services">
|
|
<h4>[customizations.services]<a class="headerlink" href="#customizations-services" title="Permalink to this headline">¶</a></h4>
|
|
<p>This section can be used to control which services are enabled at boot time.
|
|
Some image types already have services enabled or disabled in order for the
|
|
image to work correctly, and cannot be overridden. eg. <code class="docutils literal notranslate"><span class="pre">ami</span></code> requires
|
|
<code class="docutils literal notranslate"><span class="pre">sshd</span></code>, <code class="docutils literal notranslate"><span class="pre">chronyd</span></code>, and <code class="docutils literal notranslate"><span class="pre">cloud-init</span></code>. Without them the image will not
|
|
boot. Blueprint services are added to, not replacing, the list already in the
|
|
templates, if any.</p>
|
|
<p>The service names are systemd service units. You may specify any systemd unit
|
|
file accepted by <code class="docutils literal notranslate"><span class="pre">systemctl</span> <span class="pre">enable</span></code> eg. <code class="docutils literal notranslate"><span class="pre">cockpit.socket</span></code>:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">customizations</span><span class="o">.</span><span class="n">services</span><span class="p">]</span>
|
|
<span class="n">enabled</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"sshd"</span><span class="p">,</span> <span class="s2">"cockpit.socket"</span><span class="p">,</span> <span class="s2">"httpd"</span><span class="p">]</span>
|
|
<span class="n">disabled</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"postfix"</span><span class="p">,</span> <span class="s2">"telnetd"</span><span class="p">]</span>
|
|
</pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="repos-git">
|
|
<h3>[[repos.git]]<a class="headerlink" href="#repos-git" title="Permalink to this headline">¶</a></h3>
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">[[repos.git]]</span></code> entries are used to add files from a <a class="reference external" href="https://git-scm.com/">git repository</a>
|
|
repository to the created image. The repository is cloned, the specified <code class="docutils literal notranslate"><span class="pre">ref</span></code> is checked out
|
|
and an rpm is created to install the files to a <code class="docutils literal notranslate"><span class="pre">destination</span></code> path. The rpm includes a summary
|
|
with the details of the repository and reference used to create it. The rpm is also included in the
|
|
image build metadata.</p>
|
|
<p>To create an rpm named <code class="docutils literal notranslate"><span class="pre">server-config-1.0-1.noarch.rpm</span></code> you would add this to your blueprint:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[[</span><span class="n">repos</span><span class="o">.</span><span class="n">git</span><span class="p">]]</span>
|
|
<span class="n">rpmname</span><span class="o">=</span><span class="s2">"server-config"</span>
|
|
<span class="n">rpmversion</span><span class="o">=</span><span class="s2">"1.0"</span>
|
|
<span class="n">rpmrelease</span><span class="o">=</span><span class="s2">"1"</span>
|
|
<span class="n">summary</span><span class="o">=</span><span class="s2">"Setup files for server deployment"</span>
|
|
<span class="n">repo</span><span class="o">=</span><span class="s2">"PATH OF GIT REPO TO CLONE"</span>
|
|
<span class="n">ref</span><span class="o">=</span><span class="s2">"v1.0"</span>
|
|
<span class="n">destination</span><span class="o">=</span><span class="s2">"/opt/server/"</span>
|
|
</pre></div>
|
|
</div>
|
|
<ul class="simple">
|
|
<li><p>rpmname: Name of the rpm to create, also used as the prefix name in the tar archive</p></li>
|
|
<li><p>rpmversion: Version of the rpm, eg. "1.0.0"</p></li>
|
|
<li><p>rpmrelease: Release of the rpm, eg. "1"</p></li>
|
|
<li><p>summary: Summary string for the rpm</p></li>
|
|
<li><p>repo: URL of the get repo to clone and create the archive from</p></li>
|
|
<li><p>ref: Git reference to check out. eg. origin/branch-name, git tag, or git commit hash</p></li>
|
|
<li><p>destination: Path to install the / of the git repo at when installing the rpm</p></li>
|
|
</ul>
|
|
<p>An rpm will be created with the contents of the git repository referenced, with the files
|
|
being installed under <code class="docutils literal notranslate"><span class="pre">/opt/server/</span></code> in this case.</p>
|
|
<p><code class="docutils literal notranslate"><span class="pre">ref</span></code> can be any valid git reference for use with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">archive</span></code>. eg. to use the head
|
|
of a branch set it to <code class="docutils literal notranslate"><span class="pre">origin/branch-name</span></code>, a tag name, or a commit hash.</p>
|
|
<p>Note that the repository is cloned in full each time a build is started, so pointing to a
|
|
repository with a large amount of history may take a while to clone and use a significant
|
|
amount of disk space. The clone is temporary and is removed once the rpm is created.</p>
|
|
</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><code class="docutils literal notranslate"><span class="pre">livemedia-creator</span></code> supports a large number of output types, and only some of
|
|
these are currently available via <code class="docutils literal notranslate"><span class="pre">lorax-composer</span></code>. To add a new output type to
|
|
lorax-composer a kickstart file needs to be added to <code class="docutils literal notranslate"><span class="pre">./share/composer/</span></code>. The
|
|
name of the kickstart is what will be used by the <code class="docutils literal notranslate"><span class="pre">/compose/types</span></code> route, and the
|
|
<code class="docutils literal notranslate"><span class="pre">compose_type</span></code> 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"><code class="xref py py-func docutils literal notranslate"><span class="pre">pylorax.api.compose.compose_args()</span></code></a> function. The
|
|
<code class="docutils literal notranslate"><span class="pre">_MAP</span></code> 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"><code class="xref py py-func docutils literal notranslate"><span class="pre">pylorax.installer.novirt_install()</span></code></a> when it runs the compose. When the
|
|
compose is finished the output files need to be copied out of the build
|
|
directory (<code class="docutils literal notranslate"><span class="pre">/var/lib/lorax/composer/results/<UUID>/compose/</span></code>),
|
|
<a class="reference internal" href="pylorax.api.html#pylorax.api.compose.move_compose_results" title="pylorax.api.compose.move_compose_results"><code class="xref py py-func docutils literal notranslate"><span class="pre">pylorax.api.compose.move_compose_results()</span></code></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 <code class="docutils literal notranslate"><span class="pre">--make-disk</span></code> cmdline argument. To add this to lorax-composer it
|
|
needs 3 things:</p>
|
|
<ul class="simple">
|
|
<li><p>A <code class="docutils literal notranslate"><span class="pre">partitioned-disk.ks</span></code> file in <code class="docutils literal notranslate"><span class="pre">./share/composer/</span></code></p></li>
|
|
<li><p>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"><code class="xref py py-func docutils literal notranslate"><span class="pre">pylorax.api.compose.compose_args()</span></code></a></p></li>
|
|
<li><p>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"><code class="xref py py-func docutils literal notranslate"><span class="pre">pylorax.api.compose.move_compose_results()</span></code></a> to move the disk image from
|
|
the compose directory to the results directory.</p></li>
|
|
</ul>
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">partitioned-disk.ks</span></code> is pretty similar to the example minimal kickstart
|
|
in <code class="docutils literal notranslate"><span class="pre">./docs/fedora-minimal.ks</span></code>. You should remove the <code class="docutils literal notranslate"><span class="pre">url</span></code> and <code class="docutils literal notranslate"><span class="pre">repo</span></code>
|
|
commands, they will be added by the compose process. Make sure the bootloader
|
|
packages are included in the <code class="docutils literal notranslate"><span class="pre">%packages</span></code> section at the end of the kickstart,
|
|
and you will want to leave off the <code class="docutils literal notranslate"><span class="pre">%end</span></code> so that the compose can append the
|
|
list of packages from the blueprint.</p>
|
|
<p>The new <code class="docutils literal notranslate"><span class="pre">_MAP</span></code> entry should be a copy of one of the existing entries, but with <code class="docutils literal notranslate"><span class="pre">make_disk</span></code> set
|
|
to <code class="docutils literal notranslate"><span class="pre">True</span></code>. Make sure that none of the other <code class="docutils literal notranslate"><span class="pre">make_*</span></code> options are <code class="docutils literal notranslate"><span class="pre">True</span></code>. The <code class="docutils literal notranslate"><span class="pre">image_name</span></code> is
|
|
what the name of the final image will be.</p>
|
|
<p><code class="docutils literal notranslate"><span class="pre">move_compose_results()</span></code> 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 <code class="docutils literal notranslate"><span class="pre">./compose/</span></code> directory, removing any
|
|
unneeded extra files. This is especially true for the <code class="docutils literal notranslate"><span class="pre">live-iso</span></code> 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 <code class="docutils literal notranslate"><span class="pre">*.repo</span></code> files from <code class="docutils literal notranslate"><span class="pre">/etc/yum.repos.d/</span></code> into
|
|
<code class="docutils literal notranslate"><span class="pre">/var/lib/lorax/composer/repos.d/</span></code> 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 <code class="docutils literal notranslate"><span class="pre">/var/lib/lorax/composer/repos.d/</span></code> or use the
|
|
<code class="docutils literal notranslate"><span class="pre">/api/v0/projects/source/*</span></code> API routes to create them.</p>
|
|
<p>The new source can be added by doing a POST to the <code class="docutils literal notranslate"><span class="pre">/api/v0/projects/source/new</span></code>
|
|
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-default notranslate"><div class="highlight"><pre><span></span><span class="n">name</span> <span class="o">=</span> <span class="s2">"custom-source-1"</span>
|
|
<span class="n">url</span> <span class="o">=</span> <span class="s2">"https://url/path/to/repository/"</span>
|
|
<span class="nb">type</span> <span class="o">=</span> <span class="s2">"yum-baseurl"</span>
|
|
<span class="n">proxy</span> <span class="o">=</span> <span class="s2">"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="s2">"https://url/path/to/gpg-key"</span><span class="p">]</span>
|
|
</pre></div>
|
|
</div>
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">proxy</span></code> and <code class="docutils literal notranslate"><span class="pre">gpgkey_urls</span></code> entries are optional. All of the others are required. The supported
|
|
types for the urls are:</p>
|
|
<ul class="simple">
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">yum-baseurl</span></code> is a URL to a yum repository.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">yum-mirrorlist</span></code> is a URL for a mirrorlist.</p></li>
|
|
<li><p><code class="docutils literal notranslate"><span class="pre">yum-metalink</span></code> is a URL for a metalink.</p></li>
|
|
</ul>
|
|
<p>If <code class="docutils literal notranslate"><span class="pre">check_ssl</span></code> 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 <code class="docutils literal notranslate"><span class="pre">check_gpg</span></code> is true the GPG key must either be installed on the host system, or <code class="docutils literal notranslate"><span class="pre">gpgkey_urls</span></code>
|
|
should point to it.</p>
|
|
<p>You can edit an existing source (other than system sources), by doing a POST to the <code class="docutils literal notranslate"><span class="pre">new</span></code> route
|
|
with the new version of the source. It will overwrite the previous one.</p>
|
|
<p>A list of existing sources is available from <code class="docutils literal notranslate"><span class="pre">/api/v0/projects/source/list</span></code>, and detailed info
|
|
on a source can be retrieved with the <code class="docutils literal notranslate"><span class="pre">/api/v0/projects/source/info/<source-name></span></code> route. By default
|
|
it returns JSON but it can also return TOML if <code class="docutils literal notranslate"><span class="pre">?format=toml</span></code> is added to the request.</p>
|
|
<p>Non-system sources can be deleted by doing a <code class="docutils literal notranslate"><span class="pre">DELETE</span></code> request to the
|
|
<code class="docutils literal notranslate"><span class="pre">/api/v0/projects/source/delete/<source-name></span></code> 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. <code class="docutils literal notranslate"><span class="pre">lorax-composer</span></code> and <code class="docutils literal notranslate"><span class="pre">anaconda</span></code>
|
|
understand <code class="docutils literal notranslate"><span class="pre">file://</span></code> 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>Stop the <code class="docutils literal notranslate"><span class="pre">lorax-composer.service</span></code> if it is running</p></li>
|
|
<li><p>Move the repo files in <code class="docutils literal notranslate"><span class="pre">/etc/yum.repos.d/</span></code> someplace safe</p></li>
|
|
<li><p>Create a new <code class="docutils literal notranslate"><span class="pre">iso.repo</span></code> file in <code class="docutils literal notranslate"><span class="pre">/etc/yum.repos.d/</span></code>:</p>
|
|
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">iso</span><span class="p">]</span>
|
|
<span class="n">name</span><span class="o">=</span><span class="n">iso</span>
|
|
<span class="n">baseurl</span><span class="o">=</span><span class="n">file</span><span class="p">:</span><span class="o">///</span><span class="n">mnt</span><span class="o">/</span><span class="n">iso</span><span class="o">/</span>
|
|
<span class="n">enabled</span><span class="o">=</span><span class="mi">1</span>
|
|
<span class="n">gpgcheck</span><span class="o">=</span><span class="mi">1</span>
|
|
<span class="n">gpgkey</span><span class="o">=</span><span class="n">file</span><span class="p">:</span><span class="o">///</span><span class="n">mnt</span><span class="o">/</span><span class="n">iso</span><span class="o">/</span><span class="n">RPM</span><span class="o">-</span><span class="n">GPG</span><span class="o">-</span><span class="n">KEY</span><span class="o">-</span><span class="n">redhat</span><span class="o">-</span><span class="n">release</span>
|
|
</pre></div>
|
|
</div>
|
|
</li>
|
|
<li><p>Remove all the cached repo files from <code class="docutils literal notranslate"><span class="pre">/var/lib/lorax/composer/repos/</span></code></p></li>
|
|
<li><p>Restart the <code class="docutils literal notranslate"><span class="pre">lorax-composer.service</span></code></p></li>
|
|
<li><p>Check the output of <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">status</span> <span class="pre">show</span></code> for any output specific depsolve errors.
|
|
For example, the DVD usually does not include <code class="docutils literal notranslate"><span class="pre">grub2-efi-*-cdboot-*</span></code> 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 <code class="docutils literal notranslate"><span class="pre">/etc/yum.repos.d/</span></code> or clear the cached repos.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
|
|
</div>
|
|
|
|
</div>
|
|
<footer>
|
|
|
|
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
|
|
|
|
<a href="composer-cli.html" class="btn btn-neutral float-right" title="composer-cli" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right"></span></a>
|
|
|
|
|
|
<a href="livemedia-creator.html" class="btn btn-neutral float-left" title="livemedia-creator" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
|
|
|
|
</div>
|
|
|
|
|
|
<hr/>
|
|
|
|
<div role="contentinfo">
|
|
<p>
|
|
© Copyright 2018, Red Hat, Inc.
|
|
|
|
</p>
|
|
</div>
|
|
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
|
|
|
|
</footer>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
</section>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
<script type="text/javascript">
|
|
jQuery(function () {
|
|
SphinxRtdTheme.Navigation.enable(true);
|
|
});
|
|
</script>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</body>
|
|
</html> |