<ddclass="field-odd"><p>Brian C. Lane <<aclass="reference external"href="mailto:bcl%40redhat.com">bcl<span>@</span>redhat<span>.</span>com</a>></p>
<dt>compose start [--size XXXX] <BLUEPRINT><TYPE> [<IMAGE-NAME><PROVIDER><PROFILE> | <IMAGE-NAME><PROFILE.TOML>]</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] <BLUEPRINT><TYPE> [<IMAGE-NAME><PROFILE.TOML>]</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>
<dt>upload info <UPLOAD-UUID></dt><dd><p>Details about an upload</p>
</dd>
<dt>upload start <BUILD-UUID><IMAGE-NAME> [<PROVIDER><PROFILE>|<PROFILE.TOML>]</dt><dd><p>Upload a build image to the selected provider.</p>
</dd>
<dt>upload log <UPLOAD-UUID></dt><dd><p>Show the upload log</p>
</dd>
<dt>upload cancel <UPLOAD-UUID></dt><dd><p>Cancel an upload with that is queued or in progress</p>
</dd>
<dt>upload delete <UPLOAD-UUID></dt><dd><p>Delete the upload and remove it from the build</p>
</dd>
<dt>upload reset <UPLOAD-UUID></dt><dd><p>Reset the upload so that it can be tried again</p>
</dd>
<dt>providers list <PROVIDER></dt><dd><p>List the available providers, or list the <provider's> available profiles</p>
</dd>
<dt>providers show <PROVIDER><PROFILE></dt><dd><p>show the details of a specific provider's profile</p>
</dd>
<dt>providers push <PROFILE.TOML></dt><dd><p>Add a new profile, or overwrite an existing one</p>
</dd>
<dt>providers save <PROVIDER><PROFILE></dt><dd><p>Save the profile's details to a TOML file named <PROFILE>.toml</p>
</dd>
<dt>providers delete <PROVIDER><PROFILE></dt><dd><p>Delete a profile from a provider</p>
<p>Start out by listing the available blueprints using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">blueprints</span>
<spanclass="pre">list</span></code>, pick one and save it to the local directory by running <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span>
running <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">blueprints</span><spanclass="pre">push</span><spanclass="pre">http-server.toml</span></code>. You can verify that it was
saved by viewing the changelog - <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">blueprints</span><spanclass="pre">changes</span><spanclass="pre">http-server</span></code>.</p>
<p>Build a <codeclass="docutils literal notranslate"><spanclass="pre">qcow2</span></code> disk image from this blueprint by running <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span>
<spanclass="pre">compose</span><spanclass="pre">start</span><spanclass="pre">http-server</span><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">types</span></code>.
<p>Monitor it using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">status</span></code>, which will show the status of
once it is in the <codeclass="docutils literal notranslate"><spanclass="pre">RUNNING</span></code> state using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">log</span><spanclass="pre">UUID</span></code>
<p>Downloading the final image is done with <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">image</span><spanclass="pre">UUID</span></code> and it will
save the qcow2 image as <codeclass="docutils literal notranslate"><spanclass="pre">UUID-disk.qcow2</span></code> which you can then use to boot a VM like this:</p>
<h2>Image Uploads<aclass="headerlink"href="#image-uploads"title="Permalink to this headline">¶</a></h2>
<p><codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">compose</span><spanclass="pre">start</span><spanclass="pre">...</span></code> or an existing image can be uploaded
with <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">upload</span><spanclass="pre">start</span><spanclass="pre">...</span></code>. In order to access the service you need
to pass authentication details to composer-cli using a TOML file, or reference
<h2>Providers<aclass="headerlink"href="#providers"title="Permalink to this headline">¶</a></h2>
<p>Providers are the services providers with Ansible playbook support under
<codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">providers</span><spanclass="pre">template</span><spanclass="pre"><PROVIDER></span></code>, eg. for AWS
<p>Save this into an <codeclass="docutils literal notranslate"><spanclass="pre">aws-credentials.toml</span></code> file and use it when running <codeclass="docutils literal notranslate"><spanclass="pre">start</span></code>.</p>
<divclass="section"id="aws">
<h3>AWS<aclass="headerlink"href="#aws"title="Permalink to this headline">¶</a></h3>
<p>The access key and secret key can be created by going to the
<codeclass="docutils literal notranslate"><spanclass="pre">IAM->Users->Security</span><spanclass="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>
<divclass="section"id="profiles">
<h2>Profiles<aclass="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
<codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">providers</span><spanclass="pre">push</span><spanclass="pre"><PROFILE.TOML></span></code> where <codeclass="docutils literal notranslate"><spanclass="pre">PROFILE.TOML</span></code> is the same as the
provider template, but with the addition of a <codeclass="docutils literal notranslate"><spanclass="pre">profile</span></code> field. For example, an AWS
profile named <codeclass="docutils literal notranslate"><spanclass="pre">test-uploads</span></code> would look like this:</p>
<p>You can view the profile by using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">providers</span><spanclass="pre">aws</span><spanclass="pre">test-uploads</span></code>.</p>
<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 <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">upload</span><spanclass="pre">info</span><spanclass="pre"><UPLOAD-UUID></span></code></p>
<p>You can also view the upload logs from the Ansible playbook with:</p>
<p>The type of the image must match the type supported by the provider.</p>
</div>
<divclass="section"id="upload-an-existing-image">
<h2>Upload an existing image<aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">FINISHED</span></code> state, using <codeclass="docutils literal notranslate"><spanclass="pre">composer-cli</span><spanclass="pre">upload</span><spanclass="pre">start</span><spanclass="pre">...`</span></code>. If you have a profile named <codeclass="docutils literal notranslate"><spanclass="pre">test-uploads</span></code>:</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">name</span></code> field is the name of the blueprint. It can contain spaces, but they will be converted to <codeclass="docutils literal notranslate"><spanclass="pre">-</span></code>
when it is written to disk. It should be short and descriptive.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">description</span></code> can be a longer description of the blueprint, it is only used for display purposes.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">version</span></code> is a <aclass="reference external"href="https://semver.org/">semver compatible</a> version number. If
a new blueprint is uploaded with the same <codeclass="docutils literal notranslate"><spanclass="pre">version</span></code> the server will
automatically bump the PATCH level of the <codeclass="docutils literal notranslate"><spanclass="pre">version</span></code>. If the <codeclass="docutils literal notranslate"><spanclass="pre">version</span></code>
doesn't match it will be used as is. eg. Uploading a blueprint with <codeclass="docutils literal notranslate"><spanclass="pre">version</span></code>
set to <codeclass="docutils literal notranslate"><spanclass="pre">0.1.0</span></code> when the existing blueprint <codeclass="docutils literal notranslate"><spanclass="pre">version</span></code> is <codeclass="docutils literal notranslate"><spanclass="pre">0.0.1</span></code> will
result in the new blueprint being stored as <codeclass="docutils literal notranslate"><spanclass="pre">version</span><spanclass="pre">0.1.0</span></code>.</p>
<divclass="section"id="packages-and-modules">
<h3>[[packages]] and [[modules]]<aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">*</span></code> wildcards and <codeclass="docutils literal notranslate"><spanclass="pre">?</span></code>
character matching.</p>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>Currently there are no differences between <codeclass="docutils literal notranslate"><spanclass="pre">packages</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">modules</span></code>
in <codeclass="docutils literal notranslate"><spanclass="pre">osbuild-composer</span></code>. Both are treated like an rpm package dependency.</p>
</div>
<p>For example, to install <codeclass="docutils literal notranslate"><spanclass="pre">tmux-2.9a</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">openssh-server-8.*</span></code>, you would add
<h3>[[groups]]<aclass="headerlink"href="#groups"title="Permalink to this headline">¶</a></h3>
<p>The <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">anaconda-tools</span></code> group you would add this to your
<p><codeclass="docutils literal notranslate"><spanclass="pre">groups</span></code> is a TOML list, so each group needs to be listed separately, like <codeclass="docutils literal notranslate"><spanclass="pre">packages</span></code> but with
no version number.</p>
</div>
<divclass="section"id="customizations">
<h3>Customizations<aclass="headerlink"href="#customizations"title="Permalink to this headline">¶</a></h3>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">[customizations]</span></code> section can be used to configure the hostname of the final image. eg.:</p>
<p>This is optional and may be left out to use the defaults.</p>
<divclass="section"id="customizations-kernel">
<h4>[customizations.kernel]<aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">tar</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">ext4-filesystem</span></code> images since they do not include a bootloader.</p>
<p>The key will be added to the user's authorized_keys file.</p>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> expects the entire content of <codeclass="docutils literal notranslate"><spanclass="pre">~/.ssh/id_rsa.pub</span></code></p>
</div>
</div>
<divclass="section"id="customizations-user">
<h4>[[customizations.user]]<aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">name</span></code>, here is a complete example:</p>
<p>If the password starts with <codeclass="docutils literal notranslate"><spanclass="pre">$6$</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">$5$</span></code>, or <codeclass="docutils literal notranslate"><spanclass="pre">$2b$</span></code> it will be stored as
an encrypted password. Otherwise it will be treated as a plain text password.</p>
<divclass="admonition warning">
<pclass="admonition-title">Warning</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">key</span></code> expects the entire content of <codeclass="docutils literal notranslate"><spanclass="pre">~/.ssh/id_rsa.pub</span></code></p>
</div>
</div>
<divclass="section"id="customizations-group">
<h4>[[customizations.group]]<aclass="headerlink"href="#customizations-group"title="Permalink to this headline">¶</a></h4>
<p>Add a group to the image. <codeclass="docutils literal notranslate"><spanclass="pre">name</span></code> is required and <codeclass="docutils literal notranslate"><spanclass="pre">gid</span></code> is optional:</p>
<p>The values supported by <codeclass="docutils literal notranslate"><spanclass="pre">timezone</span></code> can be listed by running <codeclass="docutils literal notranslate"><spanclass="pre">timedatectl</span><spanclass="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>
<divclass="section"id="customizations-locale">
<h4>[customizations.locale]<aclass="headerlink"href="#customizations-locale"title="Permalink to this headline">¶</a></h4>
<p>Customize the locale settings for the system:</p>
<p>The values supported by <codeclass="docutils literal notranslate"><spanclass="pre">languages</span></code> can be listed by running <codeclass="docutils literal notranslate"><spanclass="pre">localectl</span><spanclass="pre">list-locales</span></code> from
the command line.</p>
<p>The values supported by <codeclass="docutils literal notranslate"><spanclass="pre">keyboard</span></code> can be listed by running <codeclass="docutils literal notranslate"><spanclass="pre">localectl</span><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">languages</span></code>
or <codeclass="docutils literal notranslate"><spanclass="pre">keyboard</span></code> must be included (or both) in the section.</p>
</div>
<divclass="section"id="customizations-firewall">
<h4>[customizations.firewall]<aclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">sshd</span></code>. This command can be used to open other ports or services. Ports are configured using
<p>Numeric ports, or their names from <codeclass="docutils literal notranslate"><spanclass="pre">/etc/services</span></code> can be used in the <codeclass="docutils literal notranslate"><spanclass="pre">ports</span></code> enabled/disabled lists.</p>
<p>The blueprint settings extend any existing settings in the image templates, so if <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">firewalld</span></code> you can specify services listed by <codeclass="docutils literal notranslate"><spanclass="pre">firewall-cmd</span><spanclass="pre">--get-services</span></code>
in a <codeclass="docutils literal notranslate"><spanclass="pre">customizations.firewall.services</span></code> section:</p>
<p>Remember that the <codeclass="docutils literal notranslate"><spanclass="pre">firewall.services</span></code> are different from the names in <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">[]</span></code>. If you
only want the default firewall setup this section can be omitted from the blueprint.</p>
<p>NOTE: The <codeclass="docutils literal notranslate"><spanclass="pre">Google</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">OpenStack</span></code> templates explicitly disable the firewall for their environment.
This cannot be overridden by the blueprint.</p>
</div>
<divclass="section"id="customizations-services">
<h4>[customizations.services]<aclass="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. <codeclass="docutils literal notranslate"><spanclass="pre">ami</span></code> requires
<codeclass="docutils literal notranslate"><spanclass="pre">sshd</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">chronyd</span></code>, and <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">systemctl</span><spanclass="pre">enable</span></code> eg. <codeclass="docutils literal notranslate"><spanclass="pre">cockpit.socket</span></code>:</p>
<h5>[[repos.git]]<aclass="headerlink"href="#repos-git"title="Permalink to this headline">¶</a></h5>
<divclass="admonition note">
<pclass="admonition-title">Note</p>
<p>Currently <codeclass="docutils literal notranslate"><spanclass="pre">osbuild-composer</span></code> does not support <codeclass="docutils literal notranslate"><spanclass="pre">repos.git</span></code></p>
</div>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">[[repos.git]]</span></code> entries are used to add files from a <aclass="reference external"href="https://git-scm.com/">git repository</a>
repository to the created image. The repository is cloned, the specified <codeclass="docutils literal notranslate"><spanclass="pre">ref</span></code> is checked out
and an rpm is created to install the files to a <codeclass="docutils literal notranslate"><spanclass="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 <codeclass="docutils literal notranslate"><spanclass="pre">server-config-1.0-1.noarch.rpm</span></code> you would add this to your blueprint:</p>
<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 <codeclass="docutils literal notranslate"><spanclass="pre">/opt/server/</span></code> in this case.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">ref</span></code> can be any valid git reference for use with <codeclass="docutils literal notranslate"><spanclass="pre">git</span><spanclass="pre">archive</span></code>. eg. to use the head
of a branch set it to <codeclass="docutils literal notranslate"><spanclass="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>
<divclass="section"id="example-blueprint">
<h2>Example Blueprint<aclass="headerlink"href="#example-blueprint"title="Permalink to this headline">¶</a></h2>
<p>This example blueprint will install the <codeclass="docutils literal notranslate"><spanclass="pre">tmux</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">git</span></code>, and <codeclass="docutils literal notranslate"><spanclass="pre">vim-enhanced</span></code>
packages. It will set the <codeclass="docutils literal notranslate"><spanclass="pre">root</span></code> ssh key, add the <codeclass="docutils literal notranslate"><spanclass="pre">widget</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">admin</span></code>
users as well as a <codeclass="docutils literal notranslate"><spanclass="pre">students</span></code> group:</p>
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
