From 05c611ee1937fdd7060537ffb41cee7b96bb359d Mon Sep 17 00:00:00 2001 From: Tudor Marcu Date: Tue, 21 Feb 2017 18:41:31 -0800 Subject: [PATCH] Update mixer docs for new tool --- source/mixer.rst | 64 +++++++++++++++++++----------------------------- 1 file changed, 25 insertions(+), 39 deletions(-) diff --git a/source/mixer.rst b/source/mixer.rst index 4cfb79bf..20edc876 100644 --- a/source/mixer.rst +++ b/source/mixer.rst @@ -34,10 +34,10 @@ Mixing # cp /usr/share/defaults/bundle-chroot-builder/builder.conf /home/clr/mix/ The file ``builder.conf`` will be read automatically from the current workspace directory, - but all of the scripts accept a ``-c/--config`` option to specify where + but the ``-config`` option exists to specify where the file is if you want to store it elsewhere. To use one in your current workspace, copy the template to /home/clr/mix. - The :file:`.yum-mix.conf` file will be auto-generated for you, as will the :file:`ClearLinuxRoot.pem`. A yum configuration is needed for the chroot-builder to know where the RPMs are hosted, and the certificate file is needed to sign the root Manifest to provide security for content verification. + The :file:`.yum-mix.conf` file will be auto-generated for you, as will the :file:`Swupd_Root.pem`. A yum configuration is needed for the chroot-builder to know where the RPMs are hosted, and the certificate file is needed to sign the root Manifest to provide security for content verification. Note there are different sections to the builder.conf. The ``[Builder]`` section provides the mixer tools with required configuration options, defining where @@ -45,8 +45,7 @@ Mixing is used by swupd-server to create an update with specific update parameters. Edit the template configuration file according to your needs. For this example, - your ``builder.conf`` should look like this, with the ``VER`` replaced by valid build - numbers, and both *URL variables set to the domain or IP of the update server:: + your ``builder.conf`` should look like this, with both *URL variables set to the domain or IP of the update server:: # vim /etc/bundle-chroot-builder/builder.conf: @@ -54,9 +53,8 @@ Mixing SERVER_STATE_DIR=/home/clr/mix/update BUNDLE_DIR=/home/clr/mix/mix-bundles YUM_CONF=/home/clr/mix/.yum-mix.conf - CERT=/home/clr/mix/ClearLinuxRoot.pem - CLEAR_VERSION=VER - MIX_VERSION=VER + CERT=/home/clr/mix/Swupd_Root.pem + VERSIONS_PATH=/home/clr/mix/ [swupd] BUNDLE=os-core-update @@ -65,7 +63,7 @@ Mixing FORMAT=1 - The SERVER_STATE_DIR is where the mix content will be outputted to, and it is automatically created for you by the mixer scripts. This can be set to any location, but for this example let us use the workspace directory. The same applies for BUNDLE_DIR; it will be generated for you in the location specified in the builder.conf, in this case - /home/clr/mix/mix-bundles. It is where the bundle definitions are stored for your mix, and where the chroot-builder looks in to know what bundles must be installed. + The SERVER_STATE_DIR is where the mix content will be outputted to, and it is automatically created for you by the mixer. This can be set to any location, but for this example let us use the workspace directory. The same applies for BUNDLE_DIR; it will be generated for you in the location specified in the builder.conf, in this case - /home/clr/mix/mix-bundles. It is where the bundle definitions are stored for your mix, and where the chroot-builder looks in to know what bundles must be installed. You may change the ``CERT=/path/to/cert`` line, which tells the chroot builder to insert the certificate specified for the mix in ``/os-core-update/usr/share/clear/update-ca/``. This is the certificate used by @@ -74,14 +72,6 @@ Mixing and verify properly. The certificate will be automatically generated for you, and the Manifest.MoM will be signed automatically as well, providing security for the update content you create. - The CLEAR_VERSION is the upstream Clear Linux* OS for Intel® Architecture version that the mix will be based - off of, and all required content (RPMs) not provided by the mixer will be downloaded from that release. - The MIX_VERSION is the version you want your mix to be. - - For this example, set CLEAR_VERSION=11580 and MIX_VERSION=10. You can of course choose any numbers you like - for the MIX_VERSION, but it is recommended to use the current latest version of upstream for the CLEAR_VERSION. - The CLEAR_VERSION can be updated as new upstream versions are released if needed. - The CONTENTURL and VERSIONURL may be an IP address, or a domain name, which hosts the /home/clr/mix/update/www (SERVER_STATE_DIR) directory. Creating a symlink to the directory in your server webdir is an easy way to host the content. A client running the mix will look to that URL to figure out if there is a new version available, and where to download update content from. @@ -89,15 +79,15 @@ Mixing https://github.com/clearlinux/swupd-server/wiki/Format-Bumps. For now leave the FORMAT value alone and do not increment it. + *The mix version and clear version will come from two state files: .mixversion and .clearversion, both of which will be created for you when you set-up the workspace and added to the VERSIONS_PATH defined. + #. **Generate the starting point for your Mix**. In your workspace, run:: - # sudo mixer-init-mix.sh + # sudo mixer init-mix -clearver 13180 -mixver 10 *If you wish to just build a mix that includes all Clear bundles with no modifications, run*:: - # sudo mixer-init-mix.sh --all-bundles - And skip to ``Creating an image``. All the required content will be automatically built, and this mix - will be identical to the version of Clear it is being composed from. + # sudo mixer init-mix -all -clearver 13180 -mixver 10 #. **Create/locate RPMs for mix.**. (Steps 4-6 are necessary only if you want to add your own RPMs to the Mix. If you are working only with Clear @@ -105,7 +95,7 @@ Mixing If you are creating RPMs from scratch, you may use ``autospec``, ``mock``, ``rpmbuild``, etc. to build them. If they are not - built on Clear, make sure your configuration and toolchain builds them correctly for Clear. + built on Clear, make sure your configuration and toolchain builds them correctly for Clear, or there is no guarantee they will be compatible. #. **Import RPMs into workspace**. The way to do this is to create an ``rpms`` directory in your workspace (for example ``/home/clr/mix/rpms``), @@ -120,7 +110,7 @@ Mixing These variables are automatically read; you simply need to run:: - # sudo mixer-add-rpms.sh + # sudo mixer add-rpms After the script exits, you should see your RPMs and a repodata directory in ``/home/clr/mix/local``. If the RPMs are not all in the local directory, check @@ -137,7 +127,7 @@ Mixing $ git add . $ git commit -s -m 'Update bundles for mix #' - You can easily copy bundles over from the ``clr-bundles/bundles`` directory in + You can easily copy bundles over from the ``clr-bundles/clr-bundles-VER/bundles/`` directory in the case that you want to simply use existing bundle sets. Note that ``mix-bundles`` should not have any folders inside of it, only bundle definitions. Do *not* modify things in the clr-bundles dir, this is simply a mirror for you to @@ -157,17 +147,17 @@ Mixing #. **Build the bundle chroots** To build all of the ``chroots`` that are based on the bundles you defined, in your workspace run:: - # sudo mixer-build-chroots.sh + # sudo mixer build-chroots If you have many bundles defined for your mix, this step may take some time. #. **Create update**. In the workspace, run:: - # sudo mixer-create-update.sh + # sudo mixer build-update - When the script completes, you'll find your mix update content under - ``/home/clr/mix/update/www/VER``, in this example, it will be located in - ``/home/clr/mix/update//www/``, where is the mix version you + When the build completes, you'll find your mix update content under + ``/home/clr/mix/update/www/VER``. In this example, it will be located in + ``/home/clr/mix/update/www/``, where is the mix version you defined, or 10 by default. All content to make a fully usable mix will be created by this step, but note that @@ -195,10 +185,9 @@ image this would be:: And lastly, set the "Version:" to say which mix version content the image should be built from, i.e. 10 for your first build. To build the image, run:: - # sudo ister.py -t release-image-config.json -V file:///home/clr/mix/update/www/ -C file:///home/clr/mix/update/www/ -f 1 + # sudo mixer build-image -format 1 -The output from this should be an image that is bootable as a VM or installable to baremetal. *Note* that -you may need to pass in -f/--format if the format you are building is different than the +The output from this should be an image that is bootable as a VM or installable to baremetal. *Note* you need to pass in -format if the format you are building is different than the format of Clear Linux OS you are currently building on. Format version can be found via:: # cat /usr/share/defaults/swupd/format @@ -206,25 +195,22 @@ Creating your next Mix version #. **Initialize next Mix version info**. To update the versions and prep for your next mix:: - Update the MIX_VERSION in your builder.conf to the next version number you want to build. + Update the .mixversion file to the next version number you want to build. From this point you can iterate through, starting again at step 4 and doing modifications as needed. For example: - Add/Remove/Modify Bundles - - sudo mixer-build-chroots.sh - - sudo mixer-create-update.sh + - sudo mixer build-chroots + - sudo mixer build-update - (Optionally) sudo mixer-pack-maker.sh --to --from -S /home/clr/mix/update Next mix created. #. **Update Bundles (Optional)**. Update ``clr-bundles``. In the workspace, run:: - # sudo mixer-update-bundles.sh + # sudo mixer get-bundles - This step is optional because the script is already called by mixer-init-mix.sh, - and only needs to be called again when you want to update the upstream clr-bundles - folder in your workspace. It also does not need to be called unless you are updating - the CLEAR_VERSION number as well to match the newest upstream release. + This step is optional because it is only needed to when you want to update the upstream clr-bundles in your workspace to a new version, which requires updating the .clearversion file.