diff --git a/source/clear-linux/guides/maintenance/mixer.rst b/source/clear-linux/guides/maintenance/mixer.rst index 1e66d117..d66e3f27 100644 --- a/source/clear-linux/guides/maintenance/mixer.rst +++ b/source/clear-linux/guides/maintenance/mixer.rst @@ -40,7 +40,7 @@ The following workflow applies if the mix includes your own #. `Create an image`_ Alternatively, the following workflow applies if the mix only uses |CL| -bundles. +content. #. `Create a workspace`_ #. `Generate the starting point for your mix`_ @@ -72,13 +72,14 @@ In your workspace, initialize mixer with the following command: .. code-block:: bash - sudo mixer init + mixer init This command initializes your workspace so you can make a mix at version 10 based on the latest released upstream |CL| version. If a :file:`builder.conf` file is not already present in your workspace, mixer creates a default -configuration file, several version and tracking files, and two bundle -directories: :file:`local-bundles` and :file:`upstream-bundles`. +configuration file. Additionally, mixer creates several version and tracking +files, and two bundle directories: :file:`local-bundles` and +:file:`upstream-bundles`. If you wish to start with a different version of upstream |CL| or a different initial mix version, you can specify these options as flags. @@ -86,44 +87,45 @@ For example: .. code-block:: bash - sudo mixer init --clear-version 21060 --mix-version 100 + mixer init --clear-version 21060 --mix-version 100 Additionally, to build a mix with your own custom RPMs, use the optional - :option:`--local-rpms` flag. For example: +:option:`--local-rpms` flag, for example: .. code-block:: bash - sudo mixer init --local-rpms + mixer init --local-rpms This command creates the :file:`local-yum` and :file:`local-rpms` directories in your mix workspace and adds their paths to the generated -:file:`builder.conf`. For more information on using these directories or +:file:`builder.conf`. If the configuration file already exists, you must add +the paths manually. For more information on using these directories or setting them up manually, see `Create or locate RPMs for the mix`_. -If all upstream |CL| bundles are part of the mix, you can easily add them all +If all upstream |CL| bundles will be part of the mix, you can easily add them all during initialization with the optional :option:`--all-upstream` flag. For example: .. code-block:: bash - sudo mixer init --all-upstream + mixer init --all-upstream Finally, you may want to track the contents of your mixer workspace with a git repository. This is a great way to track changes to your mix's content or to revert to earlier versions if something goes wrong. Mixer can set this -up automatically with the optional :option:`--git` flag. For example: +up automatically with the optional :option:`--git` flag, for example: .. code-block:: bash - sudo mixer init --git + mixer init --git .. note:: You can use any or all of the above optional flags at the same time, for example: .. code-block:: bash - sudo mixer init --clear-version 21060 --mix-version 100 --local-rpms --all-upstream --git + mixer init --clear-version 21060 --mix-version 100 --local-rpms --all-upstream --git Edit builder.conf ***************** @@ -134,7 +136,7 @@ The file :file:`builder.conf` is read automatically from the current workspace directory. Use the :option:`--config` flag during initialization to specify an alternate path to the file as needed. -The :file:`builder.conf` file has different sections. For example: +The :file:`builder.conf` file has different sections, for example: * The `[Builder]` section provides the mixer tools with the required configuration options. This section defines the path where the generated @@ -148,7 +150,7 @@ Edit the configuration file according to your needs with the command: .. code-block:: bash - sudo vim /etc/bundle-chroot-builder/builder.conf + vim /home/clr/mix/builder.conf Your version of the :file:`builder.conf` file should resemble the following example: @@ -194,8 +196,8 @@ The following variables require further explanation: :file:`/home/clr/mix/mix-bundles`. The new chroot-builder does not generate the folder at all. -* The `YUM_CONF` variable sets path where mixer automatically generates the - :file:`.yum-mix.conf` yum configuration file. The yum configuration file +* The `YUM_CONF` variable sets the path where mixer automatically generates + the :file:`.yum-mix.conf` yum configuration file. The yum configuration file points the chroot-builder to the path where the RPMs are stored. * The `CERT` variable sets the path where mixer stores the @@ -204,26 +206,31 @@ The following variables require further explanation: security for content verification. The value of the `CERT` variable can point to a different certificate. The chroot-builder inserts the certificate specified in this value into the - :file:`/os-core-update/usr/share/clear/update-ca/` path. The software - update client uses this certificate to verify the :file:`Manifest.MoM` - file's signature. For now, we **strongly** recommend that you do not - modify this line, as the certificate that `swupd` expects needs to have a - very specific configuration to sign and verify properly. Mixer - automatically generates the certificate and signs the :file:`Manifest.MoM` + :file:`/os-core-update/usr/share/clear/update-ca/` path. The software update + client uses this certificate to verify the :file:`Manifest.MoM` file's + signature. For now, we **strongly** recommend that you do not modify + this line, as the certificate that :abbr:`swupd (Software Updater)` + expects needs to have a very specific configuration to sign and verify + properly. Mixer automatically generates the certificate, if you do not + provide the path to an existing one, and signs the :file:`Manifest.MoM` file to provide security for the updated content you create. * The `CONTENTURL` and `VERSIONURL` variables set the domain or IP address - where mixer serves your updated content and the corresponding version. You - can set the `CONTENTURL` and `VERSIONURL` URL variables to the domain or IP - address of the update server. The `SERVER_STATE_DIR` directory is hosted - here: :file:`/home/clr/mix/update/www`. Creating a symlink to the directory - in your server webdir is an easy way to host the content. These URLs are - embedded in images created for your mix. The `swupd-client` looks at these - URLs to determine both if there is a new version available and the location - from which to download the updated content. Think of these links as the - equivalent to the |CL| `update page`_ but for your mix. + where swupd looks for your update content and the corresponding version. You + must set these variables to the domain or IP-address of the server hosting the + update content. You can use any web server to host your update content. To learn + how to install and configure web server using |CL|, visit + :ref:`web-server-install`. For our example, the web update content within + the `SERVER_STATE_DIR` directory is located here: + :file:`/home/clr/mix/update/www`. If the web server is on same machine as + this directory, you can create a symlink to the directory in your web + server's document root to easily host the content. These URLs are + embedded in images created for your mix. The `swupd-client` looks at + these URLs to determine if a new version is available and the location + from where to download the updated content. These links are equivalent + to the |CL| `update page`_ but for the mix. -* The `FORMAT` variable relates to the format bump. To learn more about the +* The `FORMAT` variable relates to format bumps. To learn more about the `FORMAT` option, refer to :ref:`mixer-format` and the `format bumps wiki`_. For now, leave the `FORMAT` value unchanged. @@ -247,7 +254,7 @@ building the RPMs properly, refer to our `build RPMs instructions`_. Import RPMs into workspace ************************** -#. Create a :file:`local-rpms` directory in your workspace. For example, +#. Create a :file:`local-rpms` directory in your workspace, for example, :file:`/home/clr/mix/local-rpms`. #. Copy the RPMs into the directory you created. @@ -300,23 +307,23 @@ To view the bundles already in the mix, enter the following command: .. code-block:: bash - sudo mixer bundle list + mixer bundle list This command shows a list of every bundle in the mix. Bundles can include -other bundles, and those nested bundles can themselves include other +other bundles. Those nested bundles can themselves include other bundles. When listing bundles with this command, mixer automatically recurses through the includes to show every single bundle in the mix. If you see an unexpected bundle in the list, that bundle is probably included in another bundle. Use the :option:`--tree` flag to get a better view of how -a bundle ended up in the mix. For example: +a bundle ended up in the mix, for example: .. code-block:: bash - sudo mixer bundle list --tree + mixer bundle list --tree -This command prints a tree view of the mix bundle list that explicitly shows -each included bundle. +This command shows a visual representation of the inclusion relationships +between the bundles in the mix. Bundles fall into two categories: **upstream** and **local**. @@ -334,7 +341,7 @@ bundles with the following command: .. code-block:: bash - sudo mixer bundle list upstream + mixer bundle list upstream Local bundles are bundles that you create, or are edited versions of upstream bundles. @@ -347,11 +354,11 @@ with the following command: .. code-block:: bash - sudo mixer bundle list local + mixer bundle list local Both the local and upstream :command:`bundle list` commands accept the -:option:`--tree` flag to print a tree view that explicitly shows each -included bundle. +:option:`--tree` flag to show a visual representation of the inclusion relationships +between the bundles in the mix. Edit the bundles in the mix =========================== @@ -369,17 +376,17 @@ command: .. code-block:: bash - sudo mixer bundle edit bundle1 + mixer bundle edit bundle1 -If `bundle1` is found in your local bundles, mixer edits the bundle +If `bundle1` is found in your local bundles, mixer edits this bundle definition file. If instead `bundle1` is only found upstream, mixer copies the bundle definition file from upstream into your :file:`local-bundles` directory first. In both cases, mixer launches your default editor to edit the file. When the editor closes, mixer automatically validates the edited bundle file and -reports any errors found. If mixer finds an error, you can edit the file as- -is, revert and edit, or skip and move on to the next bundle. If you skip a +reports any errors found. If mixer finds an error, you can edit the file +as-is, revert and edit, or skip and move on to the next bundle. If you skip a file, mixer saves a backup of the original file with the ``.orig`` suffix. Because mixer always checks your local bundles first, edited copies of an upstream bundle always take precedence over their upstream counterpart. You @@ -387,7 +394,7 @@ can edit multiple bundles with the following command: .. code-block:: bash - sudo mixer bundle edit bundle1 bundle2 [bundle3 ...] + mixer bundle edit bundle1 bundle2 [bundle3 ...] Create bundles for the mix ========================== @@ -398,7 +405,7 @@ command: .. code-block:: bash - sudo mixer bundle edit new-bundle + mixer bundle edit new-bundle This command generates a blank template in :file:`local-bundles` with the :file:`new-bundle` filename. Mixer launches the editor for you to fill out @@ -408,21 +415,21 @@ as part of the bundle. .. note:: - The :command:`mixer bundle edit` accepts multiple bundles at once. Thus, - you can create multiple new bundles in a single command. For example: + The :command:`mixer bundle edit` command accepts multiple bundles at once. + Thus, you can create multiple new bundles in a single command, for example: .. code-block:: bash - sudo mixer bundle edit new-bundle1 new-bundle2 [new-bundle3 ...] + mixer bundle edit new-bundle1 new-bundle2 [new-bundle3 ...] Add bundles to the mix ====================== -You can add `bundle1` to your mix with the following command: +Add `bundle1` to your mix with the following command: .. code-block:: bash - sudo mixer bundle add bundle1 + mixer bundle add bundle1 This command adds the specified bundles to the mix bundles list stored in your :file:`mixbundles` file. For each bundle you add, mixer checks your @@ -436,7 +443,7 @@ To add multiple bundles at once, use the following command: .. code-block:: bash - sudo mixer bundle add bundle1 bundle2 [bundle3 ...] + mixer bundle add bundle1 bundle2 [bundle3 ...] Remove bundles from the mix =========================== @@ -445,7 +452,7 @@ Remove `bundle1` from your mix with the following command: .. code-block:: bash - sudo mixer bundle remove bundle1 + mixer bundle remove bundle1 This command removes `bundle1` from the mix bundle list stored in your :file:`mixbundles` file. By default, this command does not remove the bundle @@ -455,7 +462,7 @@ the :option:`--local` flag: .. code-block:: bash - sudo mixer bundle remove --local bundle1 + mixer bundle remove --local bundle1 By default, removing a local bundle file with this command removes the bundle from the mix as well. To only remove the local bundle definition file, use @@ -463,7 +470,7 @@ the following command with the :option:`--mix=false` flag: .. code-block:: bash - sudo mixer bundle remove --local --mix=false bundle1 + mixer bundle remove --local --mix=false bundle1 If you remove a local, edited version of an upstream bundle and keep the bundle in the mix, the mix then references the original upstream version of @@ -476,16 +483,18 @@ bundle definition file and will produce an error. Validate the bundles in the mix =============================== -Mixer performs basic **validation** on all bundles when used -throughout the system. +Mixer performs basic validation on all bundles when used throughout the +system. -Mixer checks the validity of the bundle's syntax and name. Mixer also ensures -the bundle can be parsed. Run this validation manually on `bundle1` with the -following command: +Mixer checks the validity of the bundle's syntax and name. Optionally, you can +run this validation manually on `bundle1` with the following command: .. code-block:: bash - sudo mixer bundle validate bundle1 + mixer bundle validate bundle1 + +.. note:: This command can be useful in many circumstances. One example is + when importing already-existing local bundles from other projects. If you use the optional :option:`--strict` flag, the command additionally checks if the rest of the bundle header fields can be parsed, if the bundle @@ -495,13 +504,13 @@ following command: .. code-block:: bash - sudo mixer bundle validate --strict bundle1 + mixer bundle validate --strict bundle1 Validate multiple bundles with the following command: .. code-block:: bash - sudo mixer bundle validate bundle1 bundle2 [bundle3 ...] + mixer bundle validate bundle1 bundle2 [bundle3 ...] Managing bundles with Git ========================= @@ -513,11 +522,11 @@ file. All the :command:`mixer bundle` commands in the previous sections support an optional :option:`--git` flag. This flag automatically applies a git commit -when the command completes. For example: +when the command completes, for example: .. code-block:: bash - sudo mixer bundle remove --git bundle1 + mixer bundle remove --git bundle1 Build the bundle chroots ************************ @@ -539,7 +548,7 @@ files.** Mixer automatically deletes the contents of the :file:`mix-bundles` directory before repopulating the directory on-the-fly as mixer builds the chroots. -We have built a new chroot-builder into the mixer tool itself. While this is +We have added a new chroot-builder to the mixer tool itself. While this is currently an experimental feature, you should use the new chroot-builder. To use the new chroot-builder, use the following command with the :option:`--new-chroots` flag: @@ -597,7 +606,7 @@ create delta packs for the first build because the update is from version 0. Version 0 implicitly has no content. Thus, mixer can generate no deltas. For subsequent builds, you can run :file:`mixer-pack-maker.sh` to generate -delta content between them. For example: 10 to 20. +delta content between them, for example: 10 to 20. Create an image ***************** @@ -620,7 +629,7 @@ the configuration file with the following command: .. code-block:: bash - sudo swupd bundle add + sudo swupd bundle-add bundle1 Keeping the list of bundles in the configuration file small allows for a smaller image size. For the minimal base image, the list is: @@ -640,12 +649,9 @@ With the `ister` tool configured, build the image with the following command: sudo mixer build image --format 1 -This command outputs an image that is bootable as a virtual machine and -that can be installed on bare metal. - Mixer automatically looks for the :file:`release-image-config.json` file, but you can freely choose the filename. To use a different name, simply pass the -:option:`--template` flag when creating your image. For example: +:option:`--template` flag when creating your image, for example: .. code-block:: bash @@ -667,22 +673,22 @@ Increment the mix version number for the next mix with the following command: .. code-block:: bash - sudo mixer versions update + mixer versions update This command automatically updates the mix version stored in the :file:`mixversion` file, incrementing it by 10. To increment by a different -amount, use the :option:`--increment` flag. For example: +amount, use the :option:`--increment` flag, for example: .. code-block:: bash - sudo mixer versions update --increment 100 + mixer versions update --increment 100 Alternatively, to set the mix version to a specific value, use the -:option:`--mix-version` flag. For example: +:option:`--mix-version` flag, for example: .. code-block:: bash - sudo mixer versions update --mix-version 200 + mixer versions update --mix-version 200 The :command:`mixer versions update` command does not allow you to set the mix version to a value less than its current value. The mix version is @@ -698,30 +704,30 @@ update the upstream version of |CL| used as a base for the mix: .. code-block:: bash - sudo mixer versions update --upstream-version 21070 + mixer versions update --upstream-version 21070 This command also accepts the keyword "latest": .. code-block:: bash - sudo mixer versions update --upstream-version latest + mixer versions update --upstream-version latest This command sets the upstream version to the latest released version of -upstream |CL| within the same format version. The :command:`mixer -versions update` command does not allow you to set an upstream version to a -value that crosses an upstream format boundary. Such values require a -"format bump" build, which is currently a manual process. Refer to -:ref:`mixer-format` for more information. +upstream |CL| within the same format version. The +:command:`mixer versions update` command does not allow you to set an +upstream version to a value that crosses an upstream format boundary. +Such values require a "format bump" build, which is currently a +manual process. Refer to :ref:`mixer-format` for more information. -Learn which mix version or upstream version you are currently using with the -following command: +Optionally, you can learn which mix version or upstream version you are +currently using with the following command: .. code-block:: bash - sudo mixer versions + mixer versions At this point, you can continue to iterate through the workflows and make -modifications as needed. For example: +modifications as needed, for example: #. Add, remove, or modify bundles. #. Build the chroots with: