diff --git a/source/clear-linux/guides/tooling/mixer.rst b/source/clear-linux/guides/tooling/mixer.rst index 61bc02b3..789178c4 100644 --- a/source/clear-linux/guides/tooling/mixer.rst +++ b/source/clear-linux/guides/tooling/mixer.rst @@ -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 ` 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 ` 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 `_ @@ -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