lorax/docs/html/composer-cli.html
2021-03-03 16:40:00 -08:00

863 lines
62 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>composer-cli &mdash; Lorax 35.0 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 src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script 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="mkksiso" href="mkksiso.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">
35.0
</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="#">composer-cli</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#composer-cli-cmdline-arguments">composer-cli 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="#edit-a-blueprint">Edit a Blueprint</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-an-image">Build an image</a></li>
<li class="toctree-l2"><a class="reference internal" href="#monitor-the-build-status">Monitor the build status</a></li>
<li class="toctree-l2"><a class="reference internal" href="#download-the-image">Download the image</a></li>
<li class="toctree-l2"><a class="reference internal" href="#image-uploads">Image Uploads</a></li>
<li class="toctree-l2"><a class="reference internal" href="#providers">Providers</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#aws">AWS</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#profiles">Profiles</a></li>
<li class="toctree-l2"><a class="reference internal" href="#build-an-image-and-upload-results">Build an image and upload results</a></li>
<li class="toctree-l2"><a class="reference internal" href="#upload-an-existing-image">Upload an existing image</a></li>
<li class="toctree-l2"><a class="reference internal" href="#debugging">Debugging</a></li>
<li class="toctree-l2"><a class="reference internal" href="#blueprint-reference">Blueprint Reference</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>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#example-blueprint">Example Blueprint</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="mkksiso.html">mkksiso</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> &raquo;</li>
<li>composer-cli</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/composer-cli.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="composer-cli">
<h1>composer-cli<a class="headerlink" href="#composer-cli" 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 &lt;<a class="reference external" href="mailto:bcl&#37;&#52;&#48;redhat&#46;com">bcl<span>&#64;</span>redhat<span>&#46;</span>com</a>&gt;</p>
</dd>
</dl>
<p><code class="docutils literal notranslate"><span class="pre">composer-cli</span></code> is an interactive tool for use with a WELDR API server,
managing blueprints, exploring available packages, and building new images. As
of Fedora 34, <cite>osbuild-composer &lt;https://osbuild.org&gt;</cite> is the recommended
server.</p>
<p>It requires the server to be installed on the local system, and the user
running it needs to be a member of the <code class="docutils literal notranslate"><span class="pre">weldr</span></code> group.</p>
<div class="section" id="composer-cli-cmdline-arguments">
<h2>composer-cli cmdline arguments<a class="headerlink" href="#composer-cli-cmdline-arguments" title="Permalink to this headline"></a></h2>
<p><p>Lorax Composer commandline tool</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">composer</span><span class="o">-</span><span class="n">cli</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">j</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">s</span> <span class="n">SOCKET</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">a</span> <span class="n">APIVER</span><span class="p">]</span> <span class="p">[</span><span class="o">--</span><span class="n">test</span> <span class="n">TESTMODE</span><span class="p">]</span> <span class="p">[</span><span class="o">-</span><span class="n">V</span><span class="p">]</span> <span class="o">...</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>args</kbd></dt>
<dd></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>-j, --json</kbd></dt>
<dd><p>Output the raw JSON response instead of the normal output.</p>
<p>Default: False</p>
</dd>
<dt><kbd>-s, --socket</kbd></dt>
<dd><p>Path to the socket file to listen on</p>
<p>Default: &quot;/run/weldr/api.socket&quot;</p>
</dd>
<dt><kbd>--log</kbd></dt>
<dd><p>Path to logfile (./composer-cli.log)</p>
</dd>
<dt><kbd>-a, --api</kbd></dt>
<dd><p>API Version to use</p>
<p>Default: &quot;1&quot;</p>
</dd>
<dt><kbd>--test</kbd></dt>
<dd><p>Pass test mode to compose. 1=Mock compose with fail. 2=Mock compose with finished.</p>
<p>Default: 0</p>
</dd>
<dt><kbd>-V</kbd></dt>
<dd><p>show program's version number and exit</p>
<p>Default: False</p>
</dd>
</dl>
</div>
<p><dl class="simple">
<dt>compose start [--size XXXX] &lt;BLUEPRINT&gt; &lt;TYPE&gt; [&lt;IMAGE-NAME&gt; &lt;PROVIDER&gt; &lt;PROFILE&gt; | &lt;IMAGE-NAME&gt; &lt;PROFILE.TOML&gt;]</dt><dd><p>Start a compose using the selected blueprint and output type. Optionally start an upload.
--size is supported by osbuild-composer, and is in MiB.</p>
</dd>
<dt>compose start-ostree [--size XXXX] [--parent PARENT] [--ref REF] [--url url] &lt;BLUEPRINT&gt; &lt;TYPE&gt; [&lt;IMAGE-NAME&gt; &lt;PROFILE.TOML&gt;]</dt><dd><p>Start an ostree compose using the selected blueprint and output type. Optionally start an upload. This command
is only supported by osbuild-composer. --size is in MiB.</p>
</dd>
<dt>compose types</dt><dd><p>List the supported output types.</p>
</dd>
<dt>compose status</dt><dd><p>List the status of all running and finished composes.</p>
</dd>
<dt>compose list [waiting|running|finished|failed]</dt><dd><p>List basic information about composes.</p>
</dd>
<dt>compose log &lt;UUID&gt; [&lt;SIZE&gt;]</dt><dd><p>Show the last SIZE kB of the compose log.</p>
</dd>
<dt>compose cancel &lt;UUID&gt;</dt><dd><p>Cancel a running compose and delete any intermediate results.</p>
</dd>
<dt>compose delete &lt;UUID,...&gt;</dt><dd><p>Delete the listed compose results.</p>
</dd>
<dt>compose info &lt;UUID&gt;</dt><dd><p>Show detailed information on the compose.</p>
</dd>
<dt>compose metadata &lt;UUID&gt;</dt><dd><p>Download the metadata use to create the compose to &lt;uuid&gt;-metadata.tar</p>
</dd>
<dt>compose logs &lt;UUID&gt;</dt><dd><p>Download the compose logs to &lt;uuid&gt;-logs.tar</p>
</dd>
<dt>compose results &lt;UUID&gt;</dt><dd><p>Download all of the compose results; metadata, logs, and image to &lt;uuid&gt;.tar</p>
</dd>
<dt>compose image &lt;UUID&gt;</dt><dd><p>Download the output image from the compose. Filename depends on the type.</p>
</dd>
<dt>blueprints list</dt><dd><p>List the names of the available blueprints.</p>
</dd>
<dt>blueprints show &lt;BLUEPRINT,...&gt;</dt><dd><p>Display the blueprint in TOML format.</p>
</dd>
<dt>blueprints changes &lt;BLUEPRINT,...&gt;</dt><dd><p>Display the changes for each blueprint.</p>
</dd>
<dt>blueprints diff &lt;BLUEPRINT&gt; &lt;FROM-COMMIT&gt; &lt;TO-COMMIT&gt;</dt><dd><p>Display the differences between 2 versions of a blueprint.
FROM-COMMIT can be a commit hash or NEWEST
TO-COMMIT can be a commit hash, NEWEST, or WORKSPACE</p>
</dd>
<dt>blueprints save &lt;BLUEPRINT,...&gt;</dt><dd><p>Save the blueprint to a file, &lt;BLUEPRINT&gt;.toml</p>
</dd>
<dt>blueprints delete &lt;BLUEPRINT&gt;</dt><dd><p>Delete a blueprint from the server</p>
</dd>
<dt>blueprints depsolve &lt;BLUEPRINT,...&gt;</dt><dd><p>Display the packages needed to install the blueprint.</p>
</dd>
<dt>blueprints push &lt;BLUEPRINT&gt;</dt><dd><p>Push a blueprint TOML file to the server.</p>
</dd>
<dt>blueprints freeze &lt;BLUEPRINT,...&gt;</dt><dd><p>Display the frozen blueprint's modules and packages.</p>
</dd>
<dt>blueprints freeze show &lt;BLUEPRINT,...&gt;</dt><dd><p>Display the frozen blueprint in TOML format.</p>
</dd>
<dt>blueprints freeze save &lt;BLUEPRINT,...&gt;</dt><dd><p>Save the frozen blueprint to a file, &lt;blueprint-name&gt;.frozen.toml.</p>
</dd>
<dt>blueprints tag &lt;BLUEPRINT&gt;</dt><dd><p>Tag the most recent blueprint commit as a release.</p>
</dd>
<dt>blueprints undo &lt;BLUEPRINT&gt; &lt;COMMIT&gt;</dt><dd><p>Undo changes to a blueprint by reverting to the selected commit.</p>
</dd>
<dt>blueprints workspace &lt;BLUEPRINT&gt;</dt><dd><p>Push the blueprint TOML to the temporary workspace storage.</p>
</dd>
<dt>modules list</dt><dd><p>List the available modules.</p>
</dd>
<dt>projects list</dt><dd><p>List the available projects.</p>
</dd>
<dt>projects info &lt;PROJECT,...&gt;</dt><dd><p>Show details about the listed projects.</p>
</dd>
<dt>sources list</dt><dd><p>List the available sources</p>
</dd>
<dt>sources info &lt;SOURCE-NAME,...&gt;</dt><dd><p>Details about the source.</p>
</dd>
<dt>sources add &lt;SOURCE.TOML&gt;</dt><dd><p>Add a package source to the server.</p>
</dd>
<dt>sources change &lt;SOURCE.TOML&gt;</dt><dd><p>Change an existing source</p>
</dd>
<dt>sources delete &lt;SOURCE-NAME&gt;</dt><dd><p>Delete a package source.</p>
</dd>
</dl>
<p>status show Show API server status.</p>
<dl class="simple">
<dt>upload info &lt;UPLOAD-UUID&gt;</dt><dd><p>Details about an upload</p>
</dd>
<dt>upload start &lt;BUILD-UUID&gt; &lt;IMAGE-NAME&gt; [&lt;PROVIDER&gt; &lt;PROFILE&gt;|&lt;PROFILE.TOML&gt;]</dt><dd><p>Upload a build image to the selected provider.</p>
</dd>
<dt>upload log &lt;UPLOAD-UUID&gt;</dt><dd><p>Show the upload log</p>
</dd>
<dt>upload cancel &lt;UPLOAD-UUID&gt;</dt><dd><p>Cancel an upload with that is queued or in progress</p>
</dd>
<dt>upload delete &lt;UPLOAD-UUID&gt;</dt><dd><p>Delete the upload and remove it from the build</p>
</dd>
<dt>upload reset &lt;UPLOAD-UUID&gt;</dt><dd><p>Reset the upload so that it can be tried again</p>
</dd>
<dt>providers list &lt;PROVIDER&gt;</dt><dd><p>List the available providers, or list the &lt;provider's&gt; available profiles</p>
</dd>
<dt>providers show &lt;PROVIDER&gt; &lt;PROFILE&gt;</dt><dd><p>show the details of a specific provider's profile</p>
</dd>
<dt>providers push &lt;PROFILE.TOML&gt;</dt><dd><p>Add a new profile, or overwrite an existing one</p>
</dd>
<dt>providers save &lt;PROVIDER&gt; &lt;PROFILE&gt;</dt><dd><p>Save the profile's details to a TOML file named &lt;PROFILE&gt;.toml</p>
</dd>
<dt>providers delete &lt;PROVIDER&gt; &lt;PROFILE&gt;</dt><dd><p>Delete a profile from a provider</p>
</dd>
</dl>
</p>
</div>
<div class="section" id="edit-a-blueprint">
<h2>Edit a Blueprint<a class="headerlink" href="#edit-a-blueprint" title="Permalink to this headline"></a></h2>
<p>Start out by listing the available blueprints using <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">blueprints</span>
<span class="pre">list</span></code>, pick one and save it to the local directory by running <code class="docutils literal notranslate"><span class="pre">composer-cli</span>
<span class="pre">blueprints</span> <span class="pre">save</span> <span class="pre">http-server</span></code>.</p>
<p>Edit the file (it will be saved with a .toml extension) and change the
description, add a package or module to it. Send it back to the server by
running <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">blueprints</span> <span class="pre">push</span> <span class="pre">http-server.toml</span></code>. You can verify that it was
saved by viewing the changelog - <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">blueprints</span> <span class="pre">changes</span> <span class="pre">http-server</span></code>.</p>
<p>See the <a class="reference internal" href="#example-blueprint">Example Blueprint</a> for an example.</p>
</div>
<div class="section" id="build-an-image">
<h2>Build an image<a class="headerlink" href="#build-an-image" title="Permalink to this headline"></a></h2>
<p>Build a <code class="docutils literal notranslate"><span class="pre">qcow2</span></code> disk image from this blueprint by running <code class="docutils literal notranslate"><span class="pre">composer-cli</span>
<span class="pre">compose</span> <span class="pre">start</span> <span class="pre">http-server</span> <span class="pre">qcow2</span></code>. It will print a UUID that you can use to
keep track of the build. You can also cancel the build if needed.</p>
<p>The available types of images is displayed by <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">compose</span> <span class="pre">types</span></code>.
Currently this consists of: alibaba, ami, ext4-filesystem, google, hyper-v,
live-iso, openstack, partitioned-disk, qcow2, tar, vhd, vmdk</p>
<p>You can optionally start an upload of the finished image, see <a class="reference internal" href="#image-uploads">Image Uploads</a> for
more information.</p>
</div>
<div class="section" id="monitor-the-build-status">
<h2>Monitor the build status<a class="headerlink" href="#monitor-the-build-status" title="Permalink to this headline"></a></h2>
<p>Monitor it using <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">compose</span> <span class="pre">status</span></code>, which will show the status of
all the builds on the system. You can view the end of the anaconda build logs
once it is in the <code class="docutils literal notranslate"><span class="pre">RUNNING</span></code> state using <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">compose</span> <span class="pre">log</span> <span class="pre">UUID</span></code>
where UUID is the UUID returned by the start command.</p>
<p>Once the build is in the <code class="docutils literal notranslate"><span class="pre">FINISHED</span></code> state you can download the image.</p>
</div>
<div class="section" id="download-the-image">
<h2>Download the image<a class="headerlink" href="#download-the-image" title="Permalink to this headline"></a></h2>
<p>Downloading the final image is done with <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">compose</span> <span class="pre">image</span> <span class="pre">UUID</span></code> and it will
save the qcow2 image as <code class="docutils literal notranslate"><span class="pre">UUID-disk.qcow2</span></code> which you can then use to boot a VM like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">qemu</span><span class="o">-</span><span class="n">kvm</span> <span class="o">--</span><span class="n">name</span> <span class="n">test</span><span class="o">-</span><span class="n">image</span> <span class="o">-</span><span class="n">m</span> <span class="mi">1024</span> <span class="o">-</span><span class="n">hda</span> <span class="o">./</span><span class="n">UUID</span><span class="o">-</span><span class="n">disk</span><span class="o">.</span><span class="n">qcow2</span>
</pre></div>
</div>
</div>
<div class="section" id="image-uploads">
<h2>Image Uploads<a class="headerlink" href="#image-uploads" title="Permalink to this headline"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">composer-cli</span></code> can upload the images to a number of services, including AWS,
OpenStack, and vSphere. The upload can be started when the build is finished,
by using <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">compose</span> <span class="pre">start</span> <span class="pre">...</span></code> or an existing image can be uploaded
with <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">upload</span> <span class="pre">start</span> <span class="pre">...</span></code>. In order to access the service you need
to pass authentication details to composer-cli using a TOML file, or reference
a previously saved profile.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>With <code class="docutils literal notranslate"><span class="pre">osbuild-composer</span></code> you can only specify upload targets during
the compose process.</p>
</div>
</div>
<div class="section" id="providers">
<h2>Providers<a class="headerlink" href="#providers" title="Permalink to this headline"></a></h2>
<p>Providers are the services providers with Ansible playbook support under
<code class="docutils literal notranslate"><span class="pre">/usr/share/lorax/lifted/providers/</span></code>, you will need to gather some provider
specific information in order to authenticate with it. You can view the
required fields using <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">providers</span> <span class="pre">template</span> <span class="pre">&lt;PROVIDER&gt;</span></code>, eg. for AWS
you would run:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">composer</span><span class="o">-</span><span class="n">cli</span> <span class="n">upload</span> <span class="n">template</span> <span class="n">aws</span>
</pre></div>
</div>
<p>The output looks like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">provider</span> <span class="o">=</span> <span class="s2">&quot;aws&quot;</span>
<span class="p">[</span><span class="n">settings</span><span class="p">]</span>
<span class="n">aws_access_key</span> <span class="o">=</span> <span class="s2">&quot;AWS Access Key&quot;</span>
<span class="n">aws_bucket</span> <span class="o">=</span> <span class="s2">&quot;AWS Bucket&quot;</span>
<span class="n">aws_region</span> <span class="o">=</span> <span class="s2">&quot;AWS Region&quot;</span>
<span class="n">aws_secret_key</span> <span class="o">=</span> <span class="s2">&quot;AWS Secret Key&quot;</span>
</pre></div>
</div>
<p>Save this into an <code class="docutils literal notranslate"><span class="pre">aws-credentials.toml</span></code> file and use it when running <code class="docutils literal notranslate"><span class="pre">start</span></code>.</p>
<div class="section" id="aws">
<h3>AWS<a class="headerlink" href="#aws" title="Permalink to this headline"></a></h3>
<p>The access key and secret key can be created by going to the
<code class="docutils literal notranslate"><span class="pre">IAM-&gt;Users-&gt;Security</span> <span class="pre">Credentials</span></code> section and creating a new access key. The
secret key will only be shown when it is first created so make sure to record
it in a secure place. The region should be the region that you want to use the
AMI in, and the bucket can be an existing bucket, or a new one, following the
normal AWS bucket naming rules. It will be created if it doesn't already exist.</p>
<p>When uploading the image it is first uploaded to the s3 bucket, and then
converted to an AMI. If the conversion is successful the s3 object will be
deleted. If it fails, re-trying after correcting the problem will re-use the
object if you have not deleted it in the meantime, speeding up the process.</p>
</div>
</div>
<div class="section" id="profiles">
<h2>Profiles<a class="headerlink" href="#profiles" title="Permalink to this headline"></a></h2>
<p>Profiles store the authentication settings associated with a specific provider.
Providers can have multiple profiles, as long as their names are unique. For
example, you may have one profile for testing and another for production
uploads.</p>
<p>Profiles are created by pushing the provider settings template to the server using
<code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">providers</span> <span class="pre">push</span> <span class="pre">&lt;PROFILE.TOML&gt;</span></code> where <code class="docutils literal notranslate"><span class="pre">PROFILE.TOML</span></code> is the same as the
provider template, but with the addition of a <code class="docutils literal notranslate"><span class="pre">profile</span></code> field. For example, an AWS
profile named <code class="docutils literal notranslate"><span class="pre">test-uploads</span></code> would look like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">provider</span> <span class="o">=</span> <span class="s2">&quot;aws&quot;</span>
<span class="n">profile</span> <span class="o">=</span> <span class="s2">&quot;test-uploads&quot;</span>
<span class="p">[</span><span class="n">settings</span><span class="p">]</span>
<span class="n">aws_access_key</span> <span class="o">=</span> <span class="s2">&quot;AWS Access Key&quot;</span>
<span class="n">aws_bucket</span> <span class="o">=</span> <span class="s2">&quot;AWS Bucket&quot;</span>
<span class="n">aws_region</span> <span class="o">=</span> <span class="s2">&quot;AWS Region&quot;</span>
<span class="n">aws_secret_key</span> <span class="o">=</span> <span class="s2">&quot;AWS Secret Key&quot;</span>
</pre></div>
</div>
<p>You can view the profile by using <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">providers</span> <span class="pre">aws</span> <span class="pre">test-uploads</span></code>.</p>
</div>
<div class="section" id="build-an-image-and-upload-results">
<h2>Build an image and upload results<a class="headerlink" href="#build-an-image-and-upload-results" title="Permalink to this headline"></a></h2>
<p>If you have a profile named <code class="docutils literal notranslate"><span class="pre">test-uploads</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">composer</span><span class="o">-</span><span class="n">cli</span> <span class="n">compose</span> <span class="n">start</span> <span class="n">example</span><span class="o">-</span><span class="n">http</span><span class="o">-</span><span class="n">server</span> <span class="n">ami</span> <span class="s2">&quot;http image&quot;</span> <span class="n">aws</span> <span class="n">test</span><span class="o">-</span><span class="n">uploads</span>
</pre></div>
</div>
<p>Or if you have the settings stored in a TOML file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">composer</span><span class="o">-</span><span class="n">cli</span> <span class="n">compose</span> <span class="n">start</span> <span class="n">example</span><span class="o">-</span><span class="n">http</span><span class="o">-</span><span class="n">server</span> <span class="n">ami</span> <span class="s2">&quot;http image&quot;</span> <span class="n">aws</span><span class="o">-</span><span class="n">settings</span><span class="o">.</span><span class="n">toml</span>
</pre></div>
</div>
<p>It will return the UUID of the image build, and the UUID of the upload. Once
the build has finished successfully it will start the upload process, which you
can monitor with <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">upload</span> <span class="pre">info</span> <span class="pre">&lt;UPLOAD-UUID&gt;</span></code></p>
<p>You can also view the upload logs from the Ansible playbook with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>``composer-cli upload log &lt;UPLOAD-UUID&gt;``
</pre></div>
</div>
<p>The type of the image must match the type supported by the provider.</p>
</div>
<div class="section" id="upload-an-existing-image">
<h2>Upload an existing image<a class="headerlink" href="#upload-an-existing-image" title="Permalink to this headline"></a></h2>
<p>You can upload previously built images, as long as they are in the <code class="docutils literal notranslate"><span class="pre">FINISHED</span></code> state, using <code class="docutils literal notranslate"><span class="pre">composer-cli</span> <span class="pre">upload</span> <span class="pre">start</span> <span class="pre">...`</span></code>. If you have a profile named <code class="docutils literal notranslate"><span class="pre">test-uploads</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">composer</span><span class="o">-</span><span class="n">cli</span> <span class="n">upload</span> <span class="n">start</span> <span class="o">&lt;</span><span class="n">UUID</span><span class="o">&gt;</span> <span class="s2">&quot;http-image&quot;</span> <span class="n">aws</span> <span class="n">test</span><span class="o">-</span><span class="n">uploads</span>
</pre></div>
</div>
<p>Or if you have the settings stored in a TOML file:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">composer</span><span class="o">-</span><span class="n">cli</span> <span class="n">upload</span> <span class="n">start</span> <span class="o">&lt;</span><span class="n">UUID</span><span class="o">&gt;</span> <span class="s2">&quot;http-image&quot;</span> <span class="n">aws</span><span class="o">-</span><span class="n">settings</span><span class="o">.</span><span class="n">toml</span>
</pre></div>
</div>
<p>This will output the UUID of the upload, which can then be used to monitor the status in the same way
described above.</p>
</div>
<div class="section" id="debugging">
<h2>Debugging<a class="headerlink" href="#debugging" title="Permalink to this headline"></a></h2>
<p>There are a couple of arguments that can be helpful when debugging problems.
These are only meant for debugging and should not be used to script access to
the API. If you need to do that you can communicate with it directly in the
language of your choice.</p>
<p><code class="docutils literal notranslate"><span class="pre">--json</span></code> will return the server's response as a nicely formatted json output
instead of printing what the command would usually print.</p>
<p><code class="docutils literal notranslate"><span class="pre">--test=1</span></code> will cause a compose start to start creating an image, and then
end with a failed state.</p>
<p><code class="docutils literal notranslate"><span class="pre">--test=2</span></code> will cause a compose to start and then end with a finished state,
without actually composing anything.</p>
</div>
<div class="section" id="blueprint-reference">
<h2>Blueprint Reference<a class="headerlink" href="#blueprint-reference" 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>A basic blueprint looks 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">&quot;base&quot;</span>
<span class="n">description</span> <span class="o">=</span> <span class="s2">&quot;A base system with bash&quot;</span>
<span class="n">version</span> <span class="o">=</span> <span class="s2">&quot;0.0.1&quot;</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">&quot;bash&quot;</span>
<span class="n">version</span> <span class="o">=</span> <span class="s2">&quot;4.4.*&quot;</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>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>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">osbuild-composer</span></code>. Both are treated like an rpm package dependency.</p>
</div>
<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">&quot;tmux&quot;</span>
<span class="n">version</span> <span class="o">=</span> <span class="s2">&quot;2.9a&quot;</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">&quot;openssh-server&quot;</span>
<span class="n">version</span> <span class="o">=</span> <span class="s2">&quot;8.*&quot;</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">&quot;anaconda-tools&quot;</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">&quot;baseimage&quot;</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">&quot;nosmt=force&quot;</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">&quot;root&quot;</span>
<span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;PUBLIC SSH KEY&quot;</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">&quot;admin&quot;</span>
<span class="n">description</span> <span class="o">=</span> <span class="s2">&quot;Administrator account&quot;</span>
<span class="n">password</span> <span class="o">=</span> <span class="s2">&quot;$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31L...&quot;</span>
<span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;PUBLIC SSH KEY&quot;</span>
<span class="n">home</span> <span class="o">=</span> <span class="s2">&quot;/srv/widget/&quot;</span>
<span class="n">shell</span> <span class="o">=</span> <span class="s2">&quot;/usr/bin/bash&quot;</span>
<span class="n">groups</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;widget&quot;</span><span class="p">,</span> <span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="s2">&quot;wheel&quot;</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">&quot;widget&quot;</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">&quot;US/Eastern&quot;</span>
<span class="n">ntpservers</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;0.north-america.pool.ntp.org&quot;</span><span class="p">,</span> <span class="s2">&quot;1.north-america.pool.ntp.org&quot;</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">&quot;en_US.UTF-8&quot;</span><span class="p">]</span>
<span class="n">keyboard</span> <span class="o">=</span> <span class="s2">&quot;us&quot;</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">&quot;22:tcp&quot;</span><span class="p">,</span> <span class="s2">&quot;80:tcp&quot;</span><span class="p">,</span> <span class="s2">&quot;imap:tcp&quot;</span><span class="p">,</span> <span class="s2">&quot;53:tcp&quot;</span><span class="p">,</span> <span class="s2">&quot;53:udp&quot;</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">&quot;ftp&quot;</span><span class="p">,</span> <span class="s2">&quot;ntp&quot;</span><span class="p">,</span> <span class="s2">&quot;dhcp&quot;</span><span class="p">]</span>
<span class="n">disabled</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;telnet&quot;</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">&quot;sshd&quot;</span><span class="p">,</span> <span class="s2">&quot;cockpit.socket&quot;</span><span class="p">,</span> <span class="s2">&quot;httpd&quot;</span><span class="p">]</span>
<span class="n">disabled</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;postfix&quot;</span><span class="p">,</span> <span class="s2">&quot;telnetd&quot;</span><span class="p">]</span>
</pre></div>
</div>
<div class="section" id="repos-git">
<h5>[[repos.git]]<a class="headerlink" href="#repos-git" title="Permalink to this headline"></a></h5>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Currently <code class="docutils literal notranslate"><span class="pre">osbuild-composer</span></code> does not support <code class="docutils literal notranslate"><span class="pre">repos.git</span></code></p>
</div>
<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">&quot;server-config&quot;</span>
<span class="n">rpmversion</span><span class="o">=</span><span class="s2">&quot;1.0&quot;</span>
<span class="n">rpmrelease</span><span class="o">=</span><span class="s2">&quot;1&quot;</span>
<span class="n">summary</span><span class="o">=</span><span class="s2">&quot;Setup files for server deployment&quot;</span>
<span class="n">repo</span><span class="o">=</span><span class="s2">&quot;PATH OF GIT REPO TO CLONE&quot;</span>
<span class="n">ref</span><span class="o">=</span><span class="s2">&quot;v1.0&quot;</span>
<span class="n">destination</span><span class="o">=</span><span class="s2">&quot;/opt/server/&quot;</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. &quot;1.0.0&quot;</p></li>
<li><p>rpmrelease: Release of the rpm, eg. &quot;1&quot;</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>
</div>
<div class="section" id="example-blueprint">
<h2>Example Blueprint<a class="headerlink" href="#example-blueprint" title="Permalink to this headline"></a></h2>
<p>This example blueprint will install the <code class="docutils literal notranslate"><span class="pre">tmux</span></code>, <code class="docutils literal notranslate"><span class="pre">git</span></code>, and <code class="docutils literal notranslate"><span class="pre">vim-enhanced</span></code>
packages. It will set the <code class="docutils literal notranslate"><span class="pre">root</span></code> ssh key, add the <code class="docutils literal notranslate"><span class="pre">widget</span></code> and <code class="docutils literal notranslate"><span class="pre">admin</span></code>
users as well as a <code class="docutils literal notranslate"><span class="pre">students</span></code> group:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">name</span> <span class="o">=</span> <span class="s2">&quot;example-custom-base&quot;</span>
<span class="n">description</span> <span class="o">=</span> <span class="s2">&quot;A base system with customizations&quot;</span>
<span class="n">version</span> <span class="o">=</span> <span class="s2">&quot;0.0.1&quot;</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">&quot;tmux&quot;</span>
<span class="n">version</span> <span class="o">=</span> <span class="s2">&quot;*&quot;</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">&quot;git&quot;</span>
<span class="n">version</span> <span class="o">=</span> <span class="s2">&quot;*&quot;</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">&quot;vim-enhanced&quot;</span>
<span class="n">version</span> <span class="o">=</span> <span class="s2">&quot;*&quot;</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">&quot;custombase&quot;</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">&quot;root&quot;</span>
<span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;A SSH KEY FOR ROOT&quot;</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">&quot;widget&quot;</span>
<span class="n">description</span> <span class="o">=</span> <span class="s2">&quot;Widget process user account&quot;</span>
<span class="n">home</span> <span class="o">=</span> <span class="s2">&quot;/srv/widget/&quot;</span>
<span class="n">shell</span> <span class="o">=</span> <span class="s2">&quot;/usr/bin/false&quot;</span>
<span class="n">groups</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;dialout&quot;</span><span class="p">,</span> <span class="s2">&quot;users&quot;</span><span class="p">]</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">&quot;admin&quot;</span>
<span class="n">description</span> <span class="o">=</span> <span class="s2">&quot;Widget admin account&quot;</span>
<span class="n">password</span> <span class="o">=</span> <span class="s2">&quot;$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31LeOUleVK/R/aeWVHVZDi26zAH.o0ywBKH9Tc0/wm7sW/q39uyd1&quot;</span>
<span class="n">home</span> <span class="o">=</span> <span class="s2">&quot;/srv/widget/&quot;</span>
<span class="n">shell</span> <span class="o">=</span> <span class="s2">&quot;/usr/bin/bash&quot;</span>
<span class="n">groups</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;widget&quot;</span><span class="p">,</span> <span class="s2">&quot;users&quot;</span><span class="p">,</span> <span class="s2">&quot;students&quot;</span><span class="p">]</span>
<span class="n">uid</span> <span class="o">=</span> <span class="mi">1200</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">&quot;plain&quot;</span>
<span class="n">password</span> <span class="o">=</span> <span class="s2">&quot;simple plain password&quot;</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">&quot;bart&quot;</span>
<span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;SSH KEY FOR BART&quot;</span>
<span class="n">groups</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;students&quot;</span><span class="p">]</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">&quot;widget&quot;</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">&quot;students&quot;</span>
</pre></div>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="mkksiso.html" class="btn btn-neutral float-right" title="mkksiso" 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>
&copy; 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>