mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-11-21 19:15:51 +00:00
mixer: Adds bullet list in format bump; adds Example 3 for editors. (#659)
* Adds bullet list in format bump; adds Example 3 for editors. Signed-off-by: Michael Vincerra <michael.vincerra@intel.com> * Revise Editors example per reviewer feedback. Signed-off-by: Michael Vincerra <michael.vincerra@intel.com> * Revise to integrate form Ex. 4 into Ex. 2. Signed-off-by: Michael Vincerra <michael.vincerra@intel.com> * Integrates how to edit bundle editors in Ex. 2 and Ex. 3. Signed-off-by: Michael Vincerra <michael.vincerra@intel.com> * Respond to feedback. Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>
This commit is contained in:
@@ -3,10 +3,10 @@
|
||||
mixer
|
||||
#####
|
||||
|
||||
**mixer** is the tool used by the |CL-ATTR| team to generate official update content
|
||||
and releases. The update content generated by mixer is then consumed by swupd on
|
||||
a downstream client. The same mixer tool is available as part of |CL| to create
|
||||
your own customized update content and releases.
|
||||
**mixer** is the tool used by the |CL-ATTR| team to generate official update
|
||||
content and releases. The update content generated by mixer is then consumed
|
||||
by swupd on a downstream client. The same mixer tool is available as part of
|
||||
|CL| to create your own customized update content and releases.
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
@@ -21,19 +21,12 @@ mixer uses the following sources as inputs to generate update content:
|
||||
* Locally-defined bundles with their corresponding local RPM packages
|
||||
* Locally-defined bundles with upstream RPM packages
|
||||
|
||||
Using the mixer tool, you select which set of content from these sources will be
|
||||
part of your update. You can select content from each of these sources to make a
|
||||
unique combination of functionality for your custom update content, known as a
|
||||
**mix**.
|
||||
Using the mixer tool, you select which set of content from these sources
|
||||
will be part of your update. You can select content from each of these sources to make a unique combination of functionality for your custom update content, known as a **mix**.
|
||||
|
||||
The update content that mixer generates consists of various pieces of OS
|
||||
content, update metadata, as well as a complete image. The OS content includes
|
||||
all files in an update, as well as zero- and delta-packs for improved update
|
||||
performance. The update metadata, stored as manifests, describes all of the bundle
|
||||
information for the update. Update content produced by mixer is then published
|
||||
to a web server and consumed by clients via swupd. Refer to
|
||||
:ref:`swupd <swupd-guide>` for additional information regarding updates and
|
||||
update content.
|
||||
content, update metadata, as well as a complete image. The OS content
|
||||
includes all files in an update, as well as zero- and delta-packs for improved update performance. The update metadata, stored as manifests, describes all of the bundle information for the update. Update content produced by mixer is then published to a web server and consumed by clients via swupd. Refer to :ref:`swupd <swupd-guide>` for additional information regarding updates and update content.
|
||||
|
||||
How it works
|
||||
************
|
||||
@@ -67,7 +60,7 @@ Prerequisites
|
||||
If you use a proxy server, you must set your proxy environment variables and
|
||||
create a proxy configuration file for the Docker daemon and container.
|
||||
|
||||
Consult your IT department for the correct values if you are behind a
|
||||
Consult your IT department for the correct values if you are behind a
|
||||
corporate proxy.
|
||||
|
||||
Refer to `Configure Docker proxy info`_ for instruction.
|
||||
@@ -232,8 +225,6 @@ mixer for a new mix.
|
||||
CONTENTURL="http://192.168.25.52"
|
||||
VERSIONURL="http://192.168.25.52"
|
||||
|
||||
|
||||
|
||||
Example 2: Create a simple mix
|
||||
==============================
|
||||
|
||||
@@ -253,6 +244,27 @@ set to get a smaller kernel image, which will also be faster to load.
|
||||
mixer bundle remove kernel-native
|
||||
mixer bundle add kernel-kvm
|
||||
|
||||
#. In this case, we will add the `editors` bundle from upstream, but we will
|
||||
remove the `joe` editor.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer bundle add editors
|
||||
mixer bundle edit editors
|
||||
|
||||
#. Use an editor and manually remove `joe` from the bundle definition.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
$EDITOR ./local-bundles/editors
|
||||
|
||||
#. List the bundles in the mix again to confirm removal.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
mixer bundle list --tree
|
||||
|
||||
|
||||
#. Build bundles:
|
||||
|
||||
.. code-block:: bash
|
||||
@@ -343,8 +355,8 @@ Example 3: Deploy updates to target
|
||||
===================================
|
||||
|
||||
The image created in Example 2 is directly bootable in QEMU. In this example,
|
||||
we'll boot the image from Example 2 to verify it, and update the image from mix
|
||||
version 10 (from which the image was built), to mix version 20.
|
||||
we'll boot the image from Example 2 to verify it, and update the image from
|
||||
mix version 10 (from which the image was built), to mix version 20.
|
||||
|
||||
#. Set up the QEMU environment.
|
||||
|
||||
@@ -381,13 +393,17 @@ version 10 (from which the image was built), to mix version 20.
|
||||
swupd bundle-list
|
||||
swupd bundle-list -a
|
||||
|
||||
.. note::
|
||||
|
||||
You cannot see the curl bundle that you added in Example 2 because
|
||||
your mix is still on version 10.
|
||||
#. Now we will add the `editors` bundle that we modified.
|
||||
|
||||
Check for updates. You should see that version 20 is available. Use swupd to
|
||||
update your mix:
|
||||
.. code-block:: bash
|
||||
|
||||
swupd bundle add editors
|
||||
|
||||
#. Try to start the `joe` editor. It should not appear because we removed it
|
||||
from the original `editors` bundle.
|
||||
|
||||
#. Next we will update from version 10 to 20 to capture the newly
|
||||
available bundles. Use :command:`swupd` to update your mix:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -395,7 +411,7 @@ version 10 (from which the image was built), to mix version 20.
|
||||
swupd update
|
||||
swupd bundle-list -a
|
||||
|
||||
Now your mix should be at version 20 and curl is now available. Try using
|
||||
#. Now your mix should be at version 20 and curl is now available. Try using
|
||||
curl. This will fail because curl is not yet installed:
|
||||
|
||||
.. code-block:: console
|
||||
@@ -416,6 +432,7 @@ version 10 (from which the image was built), to mix version 20.
|
||||
|
||||
poweroff
|
||||
|
||||
|
||||
.. Example: Create a mix with custom RPM
|
||||
.. -------------------------------------
|
||||
.. TODO future example to show copy into local-rpms...
|
||||
@@ -538,30 +555,34 @@ Format version
|
||||
|
||||
Compatible versions of an OS are tracked with an OS *compatibility epoch*.
|
||||
Versions of an OS within an epoch are fully compatible and can update to any
|
||||
other version within that epoch. The compatibility epoch is set as the `Format`
|
||||
variable in the :file:`mixer.state` file. Variables in the :file:`mixer.state`
|
||||
are used by mixer between executions and should not be manually changed.
|
||||
other version within that epoch. The compatibility epoch is set as the
|
||||
`Format` variable in the :file:`mixer.state` file. Variables in the
|
||||
:file:`mixer.state` are used by mixer between executions and should not be
|
||||
manually changed.
|
||||
|
||||
If `Format` increments to a new epoch (a "format bump"), the OS has changed in
|
||||
such a way that updating from build M in format X to build N in format Y will
|
||||
not work. Generally, this scenario occurs when the software updater or the software
|
||||
has a change such that it is no longer compatible with the previous update
|
||||
scheme, or when a package is removed from the update stream and the update
|
||||
must ensure the files associated with that package are removed from the system.
|
||||
A format bump is like modifying the foundation of a house to create a new
|
||||
level. If `Format` increments to a new epoch (a "format bump"), the OS has
|
||||
changed in such a way that updating from build A in format X to build B in
|
||||
format Y will not work.
|
||||
|
||||
A format bump is required when:
|
||||
|
||||
* The software updater, :command:`swupd`, or the software is no longer
|
||||
compatible with the previous update scheme
|
||||
|
||||
* A package is removed from the update stream and the update must ensure the
|
||||
files associated with that package are removed from the system
|
||||
|
||||
Using a format increment, we make sure pre- and co-requisite changes flow out
|
||||
with proper ordering. The updated client will only update to the latest
|
||||
release in its respective format version, unless overridden by command line
|
||||
flags. In this way, we can guarantee that all clients update to the final version
|
||||
in their given format.
|
||||
flags. In this way, we can guarantee that all clients update to the final
|
||||
version in their given format.
|
||||
|
||||
The given format *must* contain all the changes needed to understand the content
|
||||
built in the next format. Only after reaching the final release in the old
|
||||
format can a client continue to update to releases in the new format.
|
||||
The given format *must* contain all the changes needed to understand the content built in the next format. Only after reaching the final release in the old format can a client continue to update to releases in the new format.
|
||||
|
||||
The format version is incremented only when a compatibility breakage is
|
||||
introduced. Normal updates, such as updating a software package, do not require a
|
||||
format increment.
|
||||
introduced. Normal updates, such as updating a software package, do not require a format increment.
|
||||
|
||||
.. rst-class:: content-collapse
|
||||
|
||||
@@ -569,44 +590,41 @@ Bundles
|
||||
=======
|
||||
|
||||
mixer stores information about the bundles included in a mix in a flat file
|
||||
called :file:`mixbundles`, which is located in the path set by the VERSIONS_PATH
|
||||
variable in :file:`builder.conf`. :file:`mixbundles` is automatically created
|
||||
when the mix is initiated. mixer will refresh the file each time you change the
|
||||
bundles in the mix.
|
||||
called :file:`mixbundles`, which is located in the path set by the VERSIONS_PATH variable in :file:`builder.conf`. :file:`mixbundles` is automatically created when the mix is initiated. mixer will refresh the file each time you change the bundles in the mix.
|
||||
|
||||
Bundles can include other bundles. Nested bundles can themselves include other
|
||||
bundles. If you see an unexpected bundle in your mix, it is likely a nested
|
||||
bundle in one of the bundles you explicitly added.
|
||||
Bundles can include other bundles. Nested bundles can themselves include
|
||||
other bundles. If you see an unexpected bundle in your mix, it is likely a
|
||||
nested bundle in one of the bundles you explicitly added.
|
||||
|
||||
A bundle will fill into one of two categories: upstream or local. Upstream
|
||||
bundles are those provided by |CL|. Local bundles are either modified upstream
|
||||
bundles or new local bundles.
|
||||
bundles are those provided by |CL|. Local bundles are either modified upstream bundles or new local bundles.
|
||||
|
||||
Upstream bundles
|
||||
----------------
|
||||
|
||||
mixer automatically downloads and caches upstream bundle definition files. These
|
||||
definition files are stored in the upstream-bundles directory in the workspace.
|
||||
Do not modify the files in this directory. This directory is simply a mirror for
|
||||
mixer to use. mixer will automatically delete the contents of this directory
|
||||
before repopulating it on-the-fly if a new version must be downloaded.
|
||||
mixer automatically downloads and caches upstream bundle definition files.
|
||||
These definition files are stored in the upstream-bundles directory in the
|
||||
workspace. Do not modify the files in this directory. This directory is
|
||||
simply a mirror for mixer to use. mixer will automatically delete the
|
||||
contents of this directory before repopulating it on-the-fly if a new
|
||||
version must be downloaded.
|
||||
|
||||
The mixer tool automatically caches the bundles for the |CL| version configured
|
||||
in the :file:`upstreamversion` file. mixer also cleans up old versions once they
|
||||
are no longer needed.
|
||||
The mixer tool automatically caches the bundles for the |CL| version
|
||||
configured in the :file:`upstreamversion` file. mixer also cleans up old
|
||||
versions once they are no longer needed.
|
||||
|
||||
Local bundles
|
||||
-------------
|
||||
|
||||
Local bundles are bundles that you create, or are edited versions of upstream
|
||||
bundles. Local bundle definition files are stored in the local-bundles directory
|
||||
in the workspace. The LOCAL_BUNDLE_DIR variable sets the path of this directory
|
||||
in the :file:`builder.conf` file.
|
||||
bundles. Local bundle definition files are stored in the local-bundles
|
||||
directory in the workspace. The LOCAL_BUNDLE_DIR variable sets the path of this directory in the :file:`builder.conf` file.
|
||||
|
||||
*mixer always checks for local bundles first and the upstream bundles second.*
|
||||
So bundles in the local-bundles directory will always take precedence over any
|
||||
upstream bundles that have the same name. This precedence enables you to copy
|
||||
upstream bundles locally, and edit into a local variation.
|
||||
*mixer always checks for local bundles first and the upstream bundles
|
||||
second.* So bundles in the local-bundles directory will always take
|
||||
precedence over any upstream bundles that have the same name. This
|
||||
precedence enables you to copy upstream bundles locally, and edit into a
|
||||
local variation.
|
||||
|
||||
Bundle configuration
|
||||
--------------------
|
||||
@@ -622,13 +640,11 @@ file in your favorite editor, making the desired edits, and saving your changes.
|
||||
.. note::
|
||||
|
||||
Removing bundles from a mix: By default, removing a bundle will only
|
||||
remove the bundle from the mix. The local bundle definition file will still
|
||||
remain. To completely remove a bundle, including its local bundle definition
|
||||
file, use the :command:`--local` flag.
|
||||
remove the bundle from the mix. The local bundle definition file will
|
||||
still remain. To completely remove a bundle, including its local bundle definition file, use the :command:`--local` flag.
|
||||
|
||||
If you remove the bundle definition file for a local, edited version of an
|
||||
upstream bundle in a mix, the mix reverts to reference the original upstream
|
||||
version of the bundle.
|
||||
upstream bundle in a mix, the mix reverts to reference the original upstream version of the bundle.
|
||||
|
||||
.. rst-class:: content-collapse
|
||||
|
||||
@@ -656,8 +672,8 @@ Pull Docker container manually (optional)
|
||||
-----------------------------------------
|
||||
|
||||
By default, mixer automatically pulls a Docker container for mixing if one
|
||||
does not already exist. If you need to troubleshoot the mixer container, it may
|
||||
be useful to manually pull a mixer Docker container.
|
||||
does not already exist. If you need to troubleshoot the mixer container, it
|
||||
may be useful to manually pull a mixer Docker container.
|
||||
|
||||
Versions of the mixer Docker container are available under the tags for the
|
||||
`clearlinux/mixer repo <https://hub.docker.com/r/clearlinux/mixer/tags/>`_
|
||||
@@ -695,7 +711,7 @@ If needed, use these steps to configure the Docker proxy information.
|
||||
.. code-block:: bash
|
||||
|
||||
sudo mkdir -p /etc/systemd/system/docker.service.d
|
||||
|
||||
|
||||
#. Create :file:`/etc/systemd/system/docker.service.d/http-proxy.conf` and
|
||||
add the following using your own proxy values:
|
||||
|
||||
@@ -711,7 +727,7 @@ If needed, use these steps to configure the Docker proxy information.
|
||||
|
||||
sudo systemctl daemon-reload
|
||||
|
||||
Configure the Docker container proxies, to pass proxy settings to
|
||||
Configure the Docker container proxies, to pass proxy settings to
|
||||
containers:
|
||||
|
||||
#. Create a directory for your container config:
|
||||
@@ -764,8 +780,8 @@ a firewall.
|
||||
Set up a nginx web server for mixer
|
||||
===================================
|
||||
|
||||
A web server is needed to host your update content. In this example, we use the
|
||||
nginx web server, which comes with |CL|.
|
||||
A web server is needed to host your update content. In this example, we use
|
||||
the nginx web server, which comes with |CL|.
|
||||
|
||||
Set up a nginx web server for mixer with the following steps:
|
||||
|
||||
@@ -781,9 +797,9 @@ Set up a nginx web server for mixer with the following steps:
|
||||
|
||||
sudo mkdir -p /var/www
|
||||
|
||||
#. Create a symbolic link between your workspace updates and the updates on the
|
||||
local nginx web server. In this example, `$HOME/mixer` is the workspace for
|
||||
the mix.
|
||||
#. Create a symbolic link between your workspace updates and the updates on
|
||||
the local nginx web server. In this example, `$HOME/mixer` is the
|
||||
workspace for the mix.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
|
||||
Reference in New Issue
Block a user