diff --git a/docs/composer-cli.rst b/docs/composer-cli.rst index 8bbf1cca..9d62f6a6 100644 --- a/docs/composer-cli.rst +++ b/docs/composer-cli.rst @@ -202,10 +202,7 @@ without actually composing anything. Blueprint Reference -=================== - -Blueprints ----------- +------------------- Blueprints are simple text files in `TOML `_ format that describe which packages, and what versions, to install into the image. They can also define a limited set @@ -234,7 +231,7 @@ set to ``0.1.0`` when the existing blueprint ``version`` is ``0.0.1`` will result in the new blueprint being stored as ``version 0.1.0``. [[packages]] and [[modules]] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ These entries describe the package names and matching version glob to be installed into the image. @@ -260,7 +257,7 @@ this to your blueprint:: [[groups]] -~~~~~~~~~~ +^^^^^^^^^^ The ``groups`` 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 @@ -282,7 +279,7 @@ no version number. Customizations -~~~~~~~~~~~~~~ +^^^^^^^^^^^^^^ The ``[customizations]`` section can be used to configure the hostname of the final image. eg.:: @@ -484,7 +481,11 @@ repository with a large amount of history may take a while to clone and use a si amount of disk space. The clone is temporary and is removed once the rpm is created. Example Blueprint -================= +----------------- + +This example blueprint will install the ``tmux``, ``git``, and ``vim-enhanced`` +packages. It will set the ``root`` ssh key, add the ``widget`` and ``admin`` +users as well as a ``students`` group:: name = "example-custom-base" description = "A base system with customizations" diff --git a/docs/html/.buildinfo b/docs/html/.buildinfo index 18864da4..55d53fdf 100644 --- a/docs/html/.buildinfo +++ b/docs/html/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: db185bc49407d9d7e5a899df753f5afa +config: d9d287449bd26afc7e34fe721edb25e6 tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/docs/html/.doctrees/composer-cli.doctree b/docs/html/.doctrees/composer-cli.doctree index d22943c0..c61a78b7 100644 Binary files a/docs/html/.doctrees/composer-cli.doctree and b/docs/html/.doctrees/composer-cli.doctree differ diff --git a/docs/html/.doctrees/composer.cli.doctree b/docs/html/.doctrees/composer.cli.doctree index 174b6a9a..48ce8ea4 100644 Binary files a/docs/html/.doctrees/composer.cli.doctree and b/docs/html/.doctrees/composer.cli.doctree differ diff --git a/docs/html/.doctrees/environment.pickle b/docs/html/.doctrees/environment.pickle index 4dff466c..0b8d7a15 100644 Binary files a/docs/html/.doctrees/environment.pickle and b/docs/html/.doctrees/environment.pickle differ diff --git a/docs/html/.doctrees/index.doctree b/docs/html/.doctrees/index.doctree index 549f05aa..3b2253c4 100644 Binary files a/docs/html/.doctrees/index.doctree and b/docs/html/.doctrees/index.doctree differ diff --git a/docs/html/.doctrees/lifted.doctree b/docs/html/.doctrees/lifted.doctree index 083c02e8..f7e18c5a 100644 Binary files a/docs/html/.doctrees/lifted.doctree and b/docs/html/.doctrees/lifted.doctree differ diff --git a/docs/html/.doctrees/livemedia-creator.doctree b/docs/html/.doctrees/livemedia-creator.doctree index e411ba43..a44ec5a0 100644 Binary files a/docs/html/.doctrees/livemedia-creator.doctree and b/docs/html/.doctrees/livemedia-creator.doctree differ diff --git a/docs/html/.doctrees/lorax-composer.doctree b/docs/html/.doctrees/lorax-composer.doctree index c567e611..7d200317 100644 Binary files a/docs/html/.doctrees/lorax-composer.doctree and b/docs/html/.doctrees/lorax-composer.doctree differ diff --git a/docs/html/.doctrees/lorax.doctree b/docs/html/.doctrees/lorax.doctree index 7ca6a136..bc096b53 100644 Binary files a/docs/html/.doctrees/lorax.doctree and b/docs/html/.doctrees/lorax.doctree differ diff --git a/docs/html/.doctrees/mkksiso.doctree b/docs/html/.doctrees/mkksiso.doctree index feb58f97..a29bf0cb 100644 Binary files a/docs/html/.doctrees/mkksiso.doctree and b/docs/html/.doctrees/mkksiso.doctree differ diff --git a/docs/html/.doctrees/modules.doctree b/docs/html/.doctrees/modules.doctree index 25540e66..058edbcf 100644 Binary files a/docs/html/.doctrees/modules.doctree and b/docs/html/.doctrees/modules.doctree differ diff --git a/docs/html/.doctrees/pylorax.doctree b/docs/html/.doctrees/pylorax.doctree index e4ed89d3..a6da55d3 100644 Binary files a/docs/html/.doctrees/pylorax.doctree and b/docs/html/.doctrees/pylorax.doctree differ diff --git a/docs/html/_modules/composer/cli.html b/docs/html/_modules/composer/cli.html index bbb2be31..eb77ef19 100644 --- a/docs/html/_modules/composer/cli.html +++ b/docs/html/_modules/composer/cli.html @@ -8,7 +8,7 @@ - composer.cli — Lorax 34.0 documentation + composer.cli — Lorax 34.3 documentation @@ -58,7 +58,7 @@
- 34.0 + 34.3
@@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/composer/cli/blueprints.html b/docs/html/_modules/composer/cli/blueprints.html index d6d49937..ca1ec1d0 100644 --- a/docs/html/_modules/composer/cli/blueprints.html +++ b/docs/html/_modules/composer/cli/blueprints.html @@ -8,7 +8,7 @@ - composer.cli.blueprints — Lorax 34.0 documentation + composer.cli.blueprints — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/composer/cli/cmdline.html b/docs/html/_modules/composer/cli/cmdline.html index c610adfc..f69757d0 100644 --- a/docs/html/_modules/composer/cli/cmdline.html +++ b/docs/html/_modules/composer/cli/cmdline.html @@ -8,7 +8,7 @@ - composer.cli.cmdline — Lorax 34.0 documentation + composer.cli.cmdline — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/composer/cli/compose.html b/docs/html/_modules/composer/cli/compose.html index a9b64ac0..dbdaab13 100644 --- a/docs/html/_modules/composer/cli/compose.html +++ b/docs/html/_modules/composer/cli/compose.html @@ -8,7 +8,7 @@ - composer.cli.compose — Lorax 34.0 documentation + composer.cli.compose — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/composer/cli/modules.html b/docs/html/_modules/composer/cli/modules.html index 64a40cb2..9cfc2738 100644 --- a/docs/html/_modules/composer/cli/modules.html +++ b/docs/html/_modules/composer/cli/modules.html @@ -8,7 +8,7 @@ - composer.cli.modules — Lorax 34.0 documentation + composer.cli.modules — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/composer/cli/projects.html b/docs/html/_modules/composer/cli/projects.html index 04459379..096e715a 100644 --- a/docs/html/_modules/composer/cli/projects.html +++ b/docs/html/_modules/composer/cli/projects.html @@ -8,7 +8,7 @@ - composer.cli.projects — Lorax 34.0 documentation + composer.cli.projects — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/composer/cli/providers.html b/docs/html/_modules/composer/cli/providers.html index 3f146ee1..10d7523a 100644 --- a/docs/html/_modules/composer/cli/providers.html +++ b/docs/html/_modules/composer/cli/providers.html @@ -8,7 +8,7 @@ - composer.cli.providers — Lorax 34.0 documentation + composer.cli.providers — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/composer/cli/sources.html b/docs/html/_modules/composer/cli/sources.html index 01af9738..d71d0fc0 100644 --- a/docs/html/_modules/composer/cli/sources.html +++ b/docs/html/_modules/composer/cli/sources.html @@ -8,7 +8,7 @@ - composer.cli.sources — Lorax 34.0 documentation + composer.cli.sources — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/composer/cli/status.html b/docs/html/_modules/composer/cli/status.html index 73776e54..a86ee4c9 100644 --- a/docs/html/_modules/composer/cli/status.html +++ b/docs/html/_modules/composer/cli/status.html @@ -8,7 +8,7 @@ - composer.cli.status — Lorax 34.0 documentation + composer.cli.status — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/composer/cli/upload.html b/docs/html/_modules/composer/cli/upload.html index a37c3516..252e4863 100644 --- a/docs/html/_modules/composer/cli/upload.html +++ b/docs/html/_modules/composer/cli/upload.html @@ -8,7 +8,7 @@ - composer.cli.upload — Lorax 34.0 documentation + composer.cli.upload — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/composer/cli/utilities.html b/docs/html/_modules/composer/cli/utilities.html index 9c65957c..f26f0c20 100644 --- a/docs/html/_modules/composer/cli/utilities.html +++ b/docs/html/_modules/composer/cli/utilities.html @@ -8,7 +8,7 @@ - composer.cli.utilities — Lorax 34.0 documentation + composer.cli.utilities — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • @@ -262,7 +261,7 @@ :type name: string :param argtype: Type to use for checking the argument value :type argtype: type - :returns (args, value) + :returns: (args, value) :rtype: tuple This removes the optional argument and value from the argument list, returns the new list, diff --git a/docs/html/_modules/composer/http_client.html b/docs/html/_modules/composer/http_client.html index 437c1efa..edaa8d47 100644 --- a/docs/html/_modules/composer/http_client.html +++ b/docs/html/_modules/composer/http_client.html @@ -8,7 +8,7 @@ - composer.http_client — Lorax 34.0 documentation + composer.http_client — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/composer/unix_socket.html b/docs/html/_modules/composer/unix_socket.html index f5b61710..cd2f95b9 100644 --- a/docs/html/_modules/composer/unix_socket.html +++ b/docs/html/_modules/composer/unix_socket.html @@ -8,7 +8,7 @@ - composer.unix_socket — Lorax 34.0 documentation + composer.unix_socket — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/index.html b/docs/html/_modules/index.html index 506cf335..d81c393e 100644 --- a/docs/html/_modules/index.html +++ b/docs/html/_modules/index.html @@ -8,7 +8,7 @@ - Overview: module code — Lorax 34.0 documentation + Overview: module code — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/lifted/config.html b/docs/html/_modules/lifted/config.html index 4319ade4..2f590111 100644 --- a/docs/html/_modules/lifted/config.html +++ b/docs/html/_modules/lifted/config.html @@ -8,7 +8,7 @@ - lifted.config — Lorax 34.0 documentation + lifted.config — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/lifted/providers.html b/docs/html/_modules/lifted/providers.html index d340f4f1..577205c6 100644 --- a/docs/html/_modules/lifted/providers.html +++ b/docs/html/_modules/lifted/providers.html @@ -8,7 +8,7 @@ - lifted.providers — Lorax 34.0 documentation + lifted.providers — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/lifted/queue.html b/docs/html/_modules/lifted/queue.html index ff1e870f..b9f79b9b 100644 --- a/docs/html/_modules/lifted/queue.html +++ b/docs/html/_modules/lifted/queue.html @@ -8,7 +8,7 @@ - lifted.queue — Lorax 34.0 documentation + lifted.queue — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/lifted/upload.html b/docs/html/_modules/lifted/upload.html index 5b922c23..fe76972a 100644 --- a/docs/html/_modules/lifted/upload.html +++ b/docs/html/_modules/lifted/upload.html @@ -8,7 +8,7 @@ - lifted.upload — Lorax 34.0 documentation + lifted.upload — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax.html b/docs/html/_modules/pylorax.html index 33de574f..9877fc52 100644 --- a/docs/html/_modules/pylorax.html +++ b/docs/html/_modules/pylorax.html @@ -8,7 +8,7 @@ - pylorax — Lorax 34.0 documentation + pylorax — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/bisect.html b/docs/html/_modules/pylorax/api/bisect.html index c7c2ae80..0ede28fe 100644 --- a/docs/html/_modules/pylorax/api/bisect.html +++ b/docs/html/_modules/pylorax/api/bisect.html @@ -8,7 +8,7 @@ - pylorax.api.bisect — Lorax 34.0 documentation + pylorax.api.bisect — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/checkparams.html b/docs/html/_modules/pylorax/api/checkparams.html index 84410b6b..9e14ce7b 100644 --- a/docs/html/_modules/pylorax/api/checkparams.html +++ b/docs/html/_modules/pylorax/api/checkparams.html @@ -8,7 +8,7 @@ - pylorax.api.checkparams — Lorax 34.0 documentation + pylorax.api.checkparams — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/cmdline.html b/docs/html/_modules/pylorax/api/cmdline.html index 07a4cec2..0aa34e91 100644 --- a/docs/html/_modules/pylorax/api/cmdline.html +++ b/docs/html/_modules/pylorax/api/cmdline.html @@ -8,7 +8,7 @@ - pylorax.api.cmdline — Lorax 34.0 documentation + pylorax.api.cmdline — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/compose.html b/docs/html/_modules/pylorax/api/compose.html index cde4a915..f9442b66 100644 --- a/docs/html/_modules/pylorax/api/compose.html +++ b/docs/html/_modules/pylorax/api/compose.html @@ -8,7 +8,7 @@ - pylorax.api.compose — Lorax 34.0 documentation + pylorax.api.compose — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/config.html b/docs/html/_modules/pylorax/api/config.html index 3b613caf..3e0f0c56 100644 --- a/docs/html/_modules/pylorax/api/config.html +++ b/docs/html/_modules/pylorax/api/config.html @@ -8,7 +8,7 @@ - pylorax.api.config — Lorax 34.0 documentation + pylorax.api.config — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/dnfbase.html b/docs/html/_modules/pylorax/api/dnfbase.html index 992e8d3c..7928b359 100644 --- a/docs/html/_modules/pylorax/api/dnfbase.html +++ b/docs/html/_modules/pylorax/api/dnfbase.html @@ -8,7 +8,7 @@ - pylorax.api.dnfbase — Lorax 34.0 documentation + pylorax.api.dnfbase — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/flask_blueprint.html b/docs/html/_modules/pylorax/api/flask_blueprint.html index 467cda25..c1bf832e 100644 --- a/docs/html/_modules/pylorax/api/flask_blueprint.html +++ b/docs/html/_modules/pylorax/api/flask_blueprint.html @@ -8,7 +8,7 @@ - pylorax.api.flask_blueprint — Lorax 34.0 documentation + pylorax.api.flask_blueprint — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/gitrpm.html b/docs/html/_modules/pylorax/api/gitrpm.html index 844fdaed..052e01d0 100644 --- a/docs/html/_modules/pylorax/api/gitrpm.html +++ b/docs/html/_modules/pylorax/api/gitrpm.html @@ -8,7 +8,7 @@ - pylorax.api.gitrpm — Lorax 34.0 documentation + pylorax.api.gitrpm — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/projects.html b/docs/html/_modules/pylorax/api/projects.html index 9f4fd097..9e76aed7 100644 --- a/docs/html/_modules/pylorax/api/projects.html +++ b/docs/html/_modules/pylorax/api/projects.html @@ -8,7 +8,7 @@ - pylorax.api.projects — Lorax 34.0 documentation + pylorax.api.projects — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/queue.html b/docs/html/_modules/pylorax/api/queue.html index 7ed5be60..63471094 100644 --- a/docs/html/_modules/pylorax/api/queue.html +++ b/docs/html/_modules/pylorax/api/queue.html @@ -8,7 +8,7 @@ - pylorax.api.queue — Lorax 34.0 documentation + pylorax.api.queue — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/recipes.html b/docs/html/_modules/pylorax/api/recipes.html index ddf35089..cdd543fd 100644 --- a/docs/html/_modules/pylorax/api/recipes.html +++ b/docs/html/_modules/pylorax/api/recipes.html @@ -8,7 +8,7 @@ - pylorax.api.recipes — Lorax 34.0 documentation + pylorax.api.recipes — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/server.html b/docs/html/_modules/pylorax/api/server.html index 9876f4f5..20debaa8 100644 --- a/docs/html/_modules/pylorax/api/server.html +++ b/docs/html/_modules/pylorax/api/server.html @@ -8,7 +8,7 @@ - pylorax.api.server — Lorax 34.0 documentation + pylorax.api.server — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/timestamp.html b/docs/html/_modules/pylorax/api/timestamp.html index 7a5b9c1c..068de384 100644 --- a/docs/html/_modules/pylorax/api/timestamp.html +++ b/docs/html/_modules/pylorax/api/timestamp.html @@ -8,7 +8,7 @@ - pylorax.api.timestamp — Lorax 34.0 documentation + pylorax.api.timestamp — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/toml.html b/docs/html/_modules/pylorax/api/toml.html index 52cd3a10..2fcb6931 100644 --- a/docs/html/_modules/pylorax/api/toml.html +++ b/docs/html/_modules/pylorax/api/toml.html @@ -8,7 +8,7 @@ - pylorax.api.toml — Lorax 34.0 documentation + pylorax.api.toml — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/utils.html b/docs/html/_modules/pylorax/api/utils.html index a442ce2b..4653e5d6 100644 --- a/docs/html/_modules/pylorax/api/utils.html +++ b/docs/html/_modules/pylorax/api/utils.html @@ -8,7 +8,7 @@ - pylorax.api.utils — Lorax 34.0 documentation + pylorax.api.utils — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/v0.html b/docs/html/_modules/pylorax/api/v0.html index d44a93d1..9360665a 100644 --- a/docs/html/_modules/pylorax/api/v0.html +++ b/docs/html/_modules/pylorax/api/v0.html @@ -8,7 +8,7 @@ - pylorax.api.v0 — Lorax 34.0 documentation + pylorax.api.v0 — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/v1.html b/docs/html/_modules/pylorax/api/v1.html index c41cbb1c..c8bf8eb0 100644 --- a/docs/html/_modules/pylorax/api/v1.html +++ b/docs/html/_modules/pylorax/api/v1.html @@ -8,7 +8,7 @@ - pylorax.api.v1 — Lorax 34.0 documentation + pylorax.api.v1 — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/api/workspace.html b/docs/html/_modules/pylorax/api/workspace.html index 6e28c7ea..45a81757 100644 --- a/docs/html/_modules/pylorax/api/workspace.html +++ b/docs/html/_modules/pylorax/api/workspace.html @@ -8,7 +8,7 @@ - pylorax.api.workspace — Lorax 34.0 documentation + pylorax.api.workspace — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/base.html b/docs/html/_modules/pylorax/base.html index b53c44a7..664607c6 100644 --- a/docs/html/_modules/pylorax/base.html +++ b/docs/html/_modules/pylorax/base.html @@ -8,7 +8,7 @@ - pylorax.base — Lorax 34.0 documentation + pylorax.base — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/buildstamp.html b/docs/html/_modules/pylorax/buildstamp.html index b5fd6fad..7e636b90 100644 --- a/docs/html/_modules/pylorax/buildstamp.html +++ b/docs/html/_modules/pylorax/buildstamp.html @@ -8,7 +8,7 @@ - pylorax.buildstamp — Lorax 34.0 documentation + pylorax.buildstamp — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/cmdline.html b/docs/html/_modules/pylorax/cmdline.html index 05052101..2e77f467 100644 --- a/docs/html/_modules/pylorax/cmdline.html +++ b/docs/html/_modules/pylorax/cmdline.html @@ -8,7 +8,7 @@ - pylorax.cmdline — Lorax 34.0 documentation + pylorax.cmdline — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/creator.html b/docs/html/_modules/pylorax/creator.html index 097e1c01..2e2d9921 100644 --- a/docs/html/_modules/pylorax/creator.html +++ b/docs/html/_modules/pylorax/creator.html @@ -8,7 +8,7 @@ - pylorax.creator — Lorax 34.0 documentation + pylorax.creator — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/decorators.html b/docs/html/_modules/pylorax/decorators.html index f0648588..b05fa0cb 100644 --- a/docs/html/_modules/pylorax/decorators.html +++ b/docs/html/_modules/pylorax/decorators.html @@ -8,7 +8,7 @@ - pylorax.decorators — Lorax 34.0 documentation + pylorax.decorators — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/discinfo.html b/docs/html/_modules/pylorax/discinfo.html index 5fe20efa..2155c799 100644 --- a/docs/html/_modules/pylorax/discinfo.html +++ b/docs/html/_modules/pylorax/discinfo.html @@ -8,7 +8,7 @@ - pylorax.discinfo — Lorax 34.0 documentation + pylorax.discinfo — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/dnfbase.html b/docs/html/_modules/pylorax/dnfbase.html index 47c3f58d..cee3800f 100644 --- a/docs/html/_modules/pylorax/dnfbase.html +++ b/docs/html/_modules/pylorax/dnfbase.html @@ -8,7 +8,7 @@ - pylorax.dnfbase — Lorax 34.0 documentation + pylorax.dnfbase — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/dnfhelper.html b/docs/html/_modules/pylorax/dnfhelper.html index a38a800c..940d6932 100644 --- a/docs/html/_modules/pylorax/dnfhelper.html +++ b/docs/html/_modules/pylorax/dnfhelper.html @@ -8,7 +8,7 @@ - pylorax.dnfhelper — Lorax 34.0 documentation + pylorax.dnfhelper — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/executils.html b/docs/html/_modules/pylorax/executils.html index 85b93740..6910337d 100644 --- a/docs/html/_modules/pylorax/executils.html +++ b/docs/html/_modules/pylorax/executils.html @@ -8,7 +8,7 @@ - pylorax.executils — Lorax 34.0 documentation + pylorax.executils — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/imgutils.html b/docs/html/_modules/pylorax/imgutils.html index af76bfbb..40785bb1 100644 --- a/docs/html/_modules/pylorax/imgutils.html +++ b/docs/html/_modules/pylorax/imgutils.html @@ -8,7 +8,7 @@ - pylorax.imgutils — Lorax 34.0 documentation + pylorax.imgutils — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/installer.html b/docs/html/_modules/pylorax/installer.html index 2e32828d..3d1656d9 100644 --- a/docs/html/_modules/pylorax/installer.html +++ b/docs/html/_modules/pylorax/installer.html @@ -8,7 +8,7 @@ - pylorax.installer — Lorax 34.0 documentation + pylorax.installer — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/ltmpl.html b/docs/html/_modules/pylorax/ltmpl.html index a8344e2b..49374bc7 100644 --- a/docs/html/_modules/pylorax/ltmpl.html +++ b/docs/html/_modules/pylorax/ltmpl.html @@ -8,7 +8,7 @@ - pylorax.ltmpl — Lorax 34.0 documentation + pylorax.ltmpl — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/monitor.html b/docs/html/_modules/pylorax/monitor.html index 767447c8..f16e2ef8 100644 --- a/docs/html/_modules/pylorax/monitor.html +++ b/docs/html/_modules/pylorax/monitor.html @@ -8,7 +8,7 @@ - pylorax.monitor — Lorax 34.0 documentation + pylorax.monitor — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/mount.html b/docs/html/_modules/pylorax/mount.html index e93c8806..ad939269 100644 --- a/docs/html/_modules/pylorax/mount.html +++ b/docs/html/_modules/pylorax/mount.html @@ -8,7 +8,7 @@ - pylorax.mount — Lorax 34.0 documentation + pylorax.mount — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/sysutils.html b/docs/html/_modules/pylorax/sysutils.html index 1e571b15..411a6a3c 100644 --- a/docs/html/_modules/pylorax/sysutils.html +++ b/docs/html/_modules/pylorax/sysutils.html @@ -8,7 +8,7 @@ - pylorax.sysutils — Lorax 34.0 documentation + pylorax.sysutils — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/treebuilder.html b/docs/html/_modules/pylorax/treebuilder.html index 7d41bacf..cc8b5c42 100644 --- a/docs/html/_modules/pylorax/treebuilder.html +++ b/docs/html/_modules/pylorax/treebuilder.html @@ -8,7 +8,7 @@ - pylorax.treebuilder — Lorax 34.0 documentation + pylorax.treebuilder — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_modules/pylorax/treeinfo.html b/docs/html/_modules/pylorax/treeinfo.html index 2f5de32f..1ed91acd 100644 --- a/docs/html/_modules/pylorax/treeinfo.html +++ b/docs/html/_modules/pylorax/treeinfo.html @@ -8,7 +8,7 @@ - pylorax.treeinfo — Lorax 34.0 documentation + pylorax.treeinfo — Lorax 34.3 documentation @@ -58,7 +58,7 @@
    - 34.0 + 34.3
    @@ -87,7 +87,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
  • mkksiso
  • Product and Updates Images
    • diff --git a/docs/html/_sources/composer-cli.rst.txt b/docs/html/_sources/composer-cli.rst.txt index 83612e1d..9d62f6a6 100644 --- a/docs/html/_sources/composer-cli.rst.txt +++ b/docs/html/_sources/composer-cli.rst.txt @@ -5,14 +5,12 @@ composer-cli Brian C. Lane ``composer-cli`` is an interactive tool for use with a WELDR API server, -managing blueprints, exploring available packages, and building new images. -`lorax-composer ` and `osbuild-composer -` both implement compatible servers. +managing blueprints, exploring available packages, and building new images. As +of Fedora 34, `osbuild-composer ` is the recommended +server. It requires the server to be installed on the local system, and the user -running it needs to be a member of the ``weldr`` group. They do not need to be -root, but all of the `security precautions `_ -apply. +running it needs to be a member of the ``weldr`` group. composer-cli cmdline arguments ------------------------------ @@ -26,15 +24,15 @@ Edit a Blueprint Start out by listing the available blueprints using ``composer-cli blueprints list``, pick one and save it to the local directory by running ``composer-cli -blueprints save http-server``. If there are no blueprints available you can -copy one of the examples `from the test suite -`_. +blueprints save http-server``. Edit the file (it will be saved with a .toml extension) and change the description, add a package or module to it. Send it back to the server by running ``composer-cli blueprints push http-server.toml``. You can verify that it was saved by viewing the changelog - ``composer-cli blueprints changes http-server``. +See the `Example Blueprint`_ for an example. + Build an image ---------------- @@ -79,9 +77,9 @@ with ``composer-cli upload start ...``. In order to access the service you need to pass authentication details to composer-cli using a TOML file, or reference a previously saved profile. -``lorax-composer`` and ``osbuild-composer`` handle this differently, with -``osbuild-composer`` you can currently only specify upload targets during the -compose process. +.. note:: + With ``osbuild-composer`` you can only specify upload targets during + the compose process. Providers @@ -201,3 +199,344 @@ end with a failed state. ``--test=2`` will cause a compose to start and then end with a finished state, without actually composing anything. + + +Blueprint Reference +------------------- + +Blueprints are simple text files in `TOML `_ format that describe +which packages, and what versions, to install into the image. They can also define a limited set +of customizations to make to the final image. + +A basic blueprint looks like this:: + + name = "base" + description = "A base system with bash" + version = "0.0.1" + + [[packages]] + name = "bash" + version = "4.4.*" + +The ``name`` field is the name of the blueprint. It can contain spaces, but they will be converted to ``-`` +when it is written to disk. It should be short and descriptive. + +``description`` can be a longer description of the blueprint, it is only used for display purposes. + +``version`` is a `semver compatible `_ version number. If +a new blueprint is uploaded with the same ``version`` the server will +automatically bump the PATCH level of the ``version``. If the ``version`` +doesn't match it will be used as is. eg. Uploading a blueprint with ``version`` +set to ``0.1.0`` when the existing blueprint ``version`` is ``0.0.1`` will +result in the new blueprint being stored as ``version 0.1.0``. + +[[packages]] and [[modules]] +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +These entries describe the package names and matching version glob to be installed into the image. + +The names must match the names exactly, and the versions can be an exact match +or a filesystem-like glob of the version using ``*`` wildcards and ``?`` +character matching. + +.. note:: + Currently there are no differences between ``packages`` and ``modules`` + in ``osbuild-composer``. Both are treated like an rpm package dependency. + +For example, to install ``tmux-2.9a`` and ``openssh-server-8.*``, you would add +this to your blueprint:: + + [[packages]] + name = "tmux" + version = "2.9a" + + [[packages]] + name = "openssh-server" + version = "8.*" + + + +[[groups]] +^^^^^^^^^^ + +The ``groups`` 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. + +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. + +For example, if you want to install the ``anaconda-tools`` group you would add this to your +blueprint:: + + [[groups]] + name="anaconda-tools" + +``groups`` is a TOML list, so each group needs to be listed separately, like ``packages`` but with +no version number. + + +Customizations +^^^^^^^^^^^^^^ + +The ``[customizations]`` section can be used to configure the hostname of the final image. eg.:: + + [customizations] + hostname = "baseimage" + +This is optional and may be left out to use the defaults. + + +[customizations.kernel] +*********************** + +This allows you to append arguments to the bootloader's kernel commandline. This will not have any +effect on ``tar`` or ``ext4-filesystem`` images since they do not include a bootloader. + +For example:: + + [customizations.kernel] + append = "nosmt=force" + + +[[customizations.sshkey]] +************************* + +Set an existing user's ssh key in the final image:: + + [[customizations.sshkey]] + user = "root" + key = "PUBLIC SSH KEY" + +The key will be added to the user's authorized_keys file. + +.. warning:: + + ``key`` expects the entire content of ``~/.ssh/id_rsa.pub`` + + +[[customizations.user]] +*********************** + +Add a user to the image, and/or set their ssh key. +All fields for this section are optional except for the ``name``, here is a complete example:: + + [[customizations.user]] + name = "admin" + description = "Administrator account" + password = "$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31L..." + key = "PUBLIC SSH KEY" + home = "/srv/widget/" + shell = "/usr/bin/bash" + groups = ["widget", "users", "wheel"] + uid = 1200 + gid = 1200 + +If the password starts with ``$6$``, ``$5$``, or ``$2b$`` it will be stored as +an encrypted password. Otherwise it will be treated as a plain text password. + +.. warning:: + + ``key`` expects the entire content of ``~/.ssh/id_rsa.pub`` + + +[[customizations.group]] +************************ + +Add a group to the image. ``name`` is required and ``gid`` is optional:: + + [[customizations.group]] + name = "widget" + gid = 1130 + + +[customizations.timezone] +************************* + +Customizing the timezone and the NTP servers to use for the system:: + + [customizations.timezone] + timezone = "US/Eastern" + ntpservers = ["0.north-america.pool.ntp.org", "1.north-america.pool.ntp.org"] + +The values supported by ``timezone`` can be listed by running ``timedatectl list-timezones``. + +If no timezone is setup the system will default to using `UTC`. The ntp servers are also +optional and will default to using the distribution defaults which are fine for most uses. + +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. + + +[customizations.locale] +*********************** + +Customize the locale settings for the system:: + + [customizations.locale] + languages = ["en_US.UTF-8"] + keyboard = "us" + +The values supported by ``languages`` can be listed by running ``localectl list-locales`` from +the command line. + +The values supported by ``keyboard`` can be listed by running ``localectl list-keymaps`` from +the command line. + +Multiple languages can be added. The first one becomes the +primary, and the others are added as secondary. One or the other of ``languages`` +or ``keyboard`` must be included (or both) in the section. + + +[customizations.firewall] +************************* + +By default the firewall blocks all access except for services that enable their ports explicitly, +like ``sshd``. This command can be used to open other ports or services. Ports are configured using +the port:protocol format:: + + [customizations.firewall] + ports = ["22:tcp", "80:tcp", "imap:tcp", "53:tcp", "53:udp"] + +Numeric ports, or their names from ``/etc/services`` can be used in the ``ports`` enabled/disabled lists. + +The blueprint settings extend any existing settings in the image templates, so if ``sshd`` is +already enabled it will extend the list of ports with the ones listed by the blueprint. + +If the distribution uses ``firewalld`` you can specify services listed by ``firewall-cmd --get-services`` +in a ``customizations.firewall.services`` section:: + + [customizations.firewall.services] + enabled = ["ftp", "ntp", "dhcp"] + disabled = ["telnet"] + +Remember that the ``firewall.services`` are different from the names in ``/etc/services``. + +Both are optional, if they are not used leave them out or set them to an empty list ``[]``. If you +only want the default firewall setup this section can be omitted from the blueprint. + +NOTE: The ``Google`` and ``OpenStack`` templates explicitly disable the firewall for their environment. +This cannot be overridden by the blueprint. + +[customizations.services] +************************* + +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. ``ami`` requires +``sshd``, ``chronyd``, and ``cloud-init``. Without them the image will not +boot. Blueprint services are added to, not replacing, the list already in the +templates, if any. + +The service names are systemd service units. You may specify any systemd unit +file accepted by ``systemctl enable`` eg. ``cockpit.socket``:: + + [customizations.services] + enabled = ["sshd", "cockpit.socket", "httpd"] + disabled = ["postfix", "telnetd"] + + +[[repos.git]] +~~~~~~~~~~~~~ + +.. note:: + Currently ``osbuild-composer`` does not support ``repos.git`` + +The ``[[repos.git]]`` entries are used to add files from a `git repository `_ +repository to the created image. The repository is cloned, the specified ``ref`` is checked out +and an rpm is created to install the files to a ``destination`` 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. + +To create an rpm named ``server-config-1.0-1.noarch.rpm`` you would add this to your blueprint:: + + [[repos.git]] + rpmname="server-config" + rpmversion="1.0" + rpmrelease="1" + summary="Setup files for server deployment" + repo="PATH OF GIT REPO TO CLONE" + ref="v1.0" + destination="/opt/server/" + +* rpmname: Name of the rpm to create, also used as the prefix name in the tar archive +* rpmversion: Version of the rpm, eg. "1.0.0" +* rpmrelease: Release of the rpm, eg. "1" +* summary: Summary string for the rpm +* repo: URL of the get repo to clone and create the archive from +* ref: Git reference to check out. eg. origin/branch-name, git tag, or git commit hash +* destination: Path to install the / of the git repo at when installing the rpm + +An rpm will be created with the contents of the git repository referenced, with the files +being installed under ``/opt/server/`` in this case. + +``ref`` can be any valid git reference for use with ``git archive``. eg. to use the head +of a branch set it to ``origin/branch-name``, a tag name, or a commit hash. + +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. + +Example Blueprint +----------------- + +This example blueprint will install the ``tmux``, ``git``, and ``vim-enhanced`` +packages. It will set the ``root`` ssh key, add the ``widget`` and ``admin`` +users as well as a ``students`` group:: + + name = "example-custom-base" + description = "A base system with customizations" + version = "0.0.1" + + [[packages]] + name = "tmux" + version = "*" + + [[packages]] + name = "git" + version = "*" + + [[packages]] + name = "vim-enhanced" + version = "*" + + [customizations] + hostname = "custombase" + + [[customizations.sshkey]] + user = "root" + key = "A SSH KEY FOR ROOT" + + [[customizations.user]] + name = "widget" + description = "Widget process user account" + home = "/srv/widget/" + shell = "/usr/bin/false" + groups = ["dialout", "users"] + + [[customizations.user]] + name = "admin" + description = "Widget admin account" + password = "$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31LeOUleVK/R/aeWVHVZDi26zAH.o0ywBKH9Tc0/wm7sW/q39uyd1" + home = "/srv/widget/" + shell = "/usr/bin/bash" + groups = ["widget", "users", "students"] + uid = 1200 + + [[customizations.user]] + name = "plain" + password = "simple plain password" + + [[customizations.user]] + name = "bart" + key = "SSH KEY FOR BART" + groups = ["students"] + + [[customizations.group]] + name = "widget" + + [[customizations.group]] + name = "students" diff --git a/docs/html/_sources/index.rst.txt b/docs/html/_sources/index.rst.txt index aae0436e..bc957e95 100644 --- a/docs/html/_sources/index.rst.txt +++ b/docs/html/_sources/index.rst.txt @@ -14,7 +14,6 @@ Contents: intro lorax livemedia-creator - lorax-composer composer-cli mkksiso product-images diff --git a/docs/html/_sources/lorax-composer.rst.txt b/docs/html/_sources/lorax-composer.rst.txt index d23be09c..903402bd 100644 --- a/docs/html/_sources/lorax-composer.rst.txt +++ b/docs/html/_sources/lorax-composer.rst.txt @@ -1,535 +1,8 @@ lorax-composer ============== -:Authors: - Brian C. Lane - -``lorax-composer`` is a WELDR API server that allows you to build disk images using -`Blueprints`_ to describe the package versions to be installed into the image. -It is compatible with the Weldr project's bdcs-api REST protocol. More -information on Weldr can be found `on the Weldr blog `_. - -Behind the scenes it uses `livemedia-creator `_ and -`Anaconda `_ to handle the -installation and configuration of the images. - -.. note:: - - ``lorax-composer`` is now deprecated. It is being replaced by the - ``osbuild-composer`` WELDR API server which implements more features (eg. - ostree, image uploads, etc.) You can still use ``composer-cli`` and - ``cockpit-composer`` with ``osbuild-composer``. See the documentation or - the `osbuild website `_ for more information. - - -Important Things To Note ------------------------- - -* As of version 30.7 SELinux can be set to Enforcing. The current state is - logged for debugging purposes and if there are SELinux denials they should - be reported as a bug. - -* All image types lock the root account, except for live-iso. You will need to either - use one of the `Customizations`_ methods for setting a ssh key/password, install a - package that creates a user, or use something like `cloud-init` to setup access at - boot time. - - -Installation ------------- - -The best way to install ``lorax-composer`` is to use ``sudo dnf install -lorax-composer composer-cli``, this will setup the weldr user and install the -systemd socket activation service. You will then need to enable it with ``sudo -systemctl enable lorax-composer.socket && sudo systemctl start -lorax-composer.socket``. This will leave the server off until the first request -is made. Systemd will then launch the server and it will remain running until -the system is rebooted. This will cause some delay in responding to the first -request from the UI or `composer-cli`. - -.. note:: - - If you want lorax-composer to respond immediately to the first request you can - start and enable `lorax-composer.service` instead of `lorax-composer.socket` - -Quickstart ----------- - -1. Create a ``weldr`` user and group by running ``useradd weldr`` -2. Remove any pre-existing socket directory with ``rm -rf /run/weldr/`` - A new directory with correct permissions will be created the first time the server runs. -3. Enable the socket activation with ``systemctl enable lorax-composer.socket - && sudo systemctl start lorax-composer.socket``. - -NOTE: You can also run it directly with ``lorax-composer /path/to/blueprints``. However, -``lorax-composer`` does not react well to being started both on the command line and via -socket activation at the same time. It is therefore recommended that you run it directly -on the command line only for testing or development purposes. For real use or development -of other projects that simply use the API, you should stick to socket activation only. - -The ``/path/to/blueprints/`` directory is where the blueprints' git repo will -be created, and all the blueprints created with the ``/api/v0/blueprints/new`` -route will be stored. If there are blueprint ``.toml`` files in the top level -of the directory they will be imported into the blueprint git storage when -``lorax-composer`` starts. - -Logs ----- - -Logs are stored under ``/var/log/lorax-composer/`` and include all console -messages as well as extra debugging info and API requests. - -Security --------- - -Some security related issues that you should be aware of before running ``lorax-composer``: - -* One of the API server threads needs to retain root privileges in order to run Anaconda. -* Only allow authorized users access to the ``weldr`` group and socket. - -Since Anaconda kickstarts are used there is the possibility that a user could -inject commands into a blueprint that would result in the kickstart executing -arbitrary code on the host. Only authorized users should be allowed to build -images using ``lorax-composer``. - -lorax-composer cmdline arguments --------------------------------- - -.. argparse:: - :ref: pylorax.api.cmdline.lorax_composer_parser - :prog: lorax-composer - - -How it Works ------------- - -The server runs as root, and as ``weldr``. Communication with it is via a unix -domain socket (``/run/weldr/api.socket`` by default). The directory and socket -are owned by ``root:weldr`` so that any user in the ``weldr`` group can use the API -to control ``lorax-composer``. - -At startup the server will check for the correct permissions and -ownership of a pre-existing directory, or it will create a new one if it -doesn't exist. The socket path and group owner's name can be changed from the -cmdline by passing it the ``--socket`` and ``--group`` arguments. - -It will then drop root privileges for the API thread and run as the ``weldr`` -user. The queue and compose thread still runs as root because it needs to be -able to mount/umount files and run Anaconda. - -Composing Images ----------------- - -The `welder-web `_ GUI project can be used to construct -blueprints and create composes using a web browser. - -Or use the command line with `composer-cli `_. - -Blueprints ----------- - -Blueprints are simple text files in `TOML `_ format that describe -which packages, and what versions, to install into the image. They can also define a limited set -of customizations to make to the final image. - -Example blueprints can be found in the ``lorax-composer`` `test suite -`_, with a simple one -looking like this:: - - name = "base" - description = "A base system with bash" - version = "0.0.1" - - [[packages]] - name = "bash" - version = "4.4.*" - -The ``name`` field is the name of the blueprint. It can contain spaces, but they will be converted to ``-`` -when it is written to disk. It should be short and descriptive. - -``description`` can be a longer description of the blueprint, it is only used for display purposes. - -``version`` is a `semver compatible `_ version number. If -a new blueprint is uploaded with the same ``version`` the server will -automatically bump the PATCH level of the ``version``. If the ``version`` -doesn't match it will be used as is. eg. Uploading a blueprint with ``version`` -set to ``0.1.0`` when the existing blueprint ``version`` is ``0.0.1`` will -result in the new blueprint being stored as ``version 0.1.0``. - -[[packages]] and [[modules]] -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -These entries describe the package names and matching version glob to be installed into the image. - -The names must match the names exactly, and the versions can be an exact match -or a filesystem-like glob of the version using ``*`` wildcards and ``?`` -character matching. - -NOTE: Currently there are no differences between ``packages`` and ``modules`` -in ``lorax-composer``. Both are treated like an rpm package dependency. - -For example, to install ``tmux-2.9a`` and ``openssh-server-8.*``, you would add -this to your blueprint:: - - [[packages]] - name = "tmux" - version = "2.9a" - - [[packages]] - name = "openssh-server" - version = "8.*" - - - -[[groups]] -~~~~~~~~~~ - -The ``groups`` 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. - -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. - -For example, if you want to install the ``anaconda-tools`` group you would add this to your -blueprint:: - - [[groups]] - name="anaconda-tools" - -``groups`` is a TOML list, so each group needs to be listed separately, like ``packages`` but with -no version number. - - -Customizations -~~~~~~~~~~~~~~ - -The ``[customizations]`` section can be used to configure the hostname of the final image. eg.:: - - [customizations] - hostname = "baseimage" - -This is optional and may be left out to use the defaults. - - -[customizations.kernel] -*********************** - -This allows you to append arguments to the bootloader's kernel commandline. This will not have any -effect on ``tar`` or ``ext4-filesystem`` images since they do not include a bootloader. - -For example:: - - [customizations.kernel] - append = "nosmt=force" - - -[[customizations.sshkey]] -************************* - -Set an existing user's ssh key in the final image:: - - [[customizations.sshkey]] - user = "root" - key = "PUBLIC SSH KEY" - -The key will be added to the user's authorized_keys file. - -.. warning:: - - ``key`` expects the entire content of ``~/.ssh/id_rsa.pub`` - - -[[customizations.user]] -*********************** - -Add a user to the image, and/or set their ssh key. -All fields for this section are optional except for the ``name``, here is a complete example:: - - [[customizations.user]] - name = "admin" - description = "Administrator account" - password = "$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31L..." - key = "PUBLIC SSH KEY" - home = "/srv/widget/" - shell = "/usr/bin/bash" - groups = ["widget", "users", "wheel"] - uid = 1200 - gid = 1200 - -If the password starts with ``$6$``, ``$5$``, or ``$2b$`` it will be stored as -an encrypted password. Otherwise it will be treated as a plain text password. - -.. warning:: - - ``key`` expects the entire content of ``~/.ssh/id_rsa.pub`` - - -[[customizations.group]] -************************ - -Add a group to the image. ``name`` is required and ``gid`` is optional:: - - [[customizations.group]] - name = "widget" - gid = 1130 - - -[customizations.timezone] -************************* - -Customizing the timezone and the NTP servers to use for the system:: - - [customizations.timezone] - timezone = "US/Eastern" - ntpservers = ["0.north-america.pool.ntp.org", "1.north-america.pool.ntp.org"] - -The values supported by ``timezone`` can be listed by running ``timedatectl list-timezones``. - -If no timezone is setup the system will default to using `UTC`. The ntp servers are also -optional and will default to using the distribution defaults which are fine for most uses. - -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. - - -[customizations.locale] -*********************** - -Customize the locale settings for the system:: - - [customizations.locale] - languages = ["en_US.UTF-8"] - keyboard = "us" - -The values supported by ``languages`` can be listed by running ``localectl list-locales`` from -the command line. - -The values supported by ``keyboard`` can be listed by running ``localectl list-keymaps`` from -the command line. - -Multiple languages can be added. The first one becomes the -primary, and the others are added as secondary. One or the other of ``languages`` -or ``keyboard`` must be included (or both) in the section. - - -[customizations.firewall] -************************* - -By default the firewall blocks all access except for services that enable their ports explicitly, -like ``sshd``. This command can be used to open other ports or services. Ports are configured using -the port:protocol format:: - - [customizations.firewall] - ports = ["22:tcp", "80:tcp", "imap:tcp", "53:tcp", "53:udp"] - -Numeric ports, or their names from ``/etc/services`` can be used in the ``ports`` enabled/disabled lists. - -The blueprint settings extend any existing settings in the image templates, so if ``sshd`` is -already enabled it will extend the list of ports with the ones listed by the blueprint. - -If the distribution uses ``firewalld`` you can specify services listed by ``firewall-cmd --get-services`` -in a ``customizations.firewall.services`` section:: - - [customizations.firewall.services] - enabled = ["ftp", "ntp", "dhcp"] - disabled = ["telnet"] - -Remember that the ``firewall.services`` are different from the names in ``/etc/services``. - -Both are optional, if they are not used leave them out or set them to an empty list ``[]``. If you -only want the default firewall setup this section can be omitted from the blueprint. - -NOTE: The ``Google`` and ``OpenStack`` templates explicitly disable the firewall for their environment. -This cannot be overridden by the blueprint. - -[customizations.services] -************************* - -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. ``ami`` requires -``sshd``, ``chronyd``, and ``cloud-init``. Without them the image will not -boot. Blueprint services are added to, not replacing, the list already in the -templates, if any. - -The service names are systemd service units. You may specify any systemd unit -file accepted by ``systemctl enable`` eg. ``cockpit.socket``:: - - [customizations.services] - enabled = ["sshd", "cockpit.socket", "httpd"] - disabled = ["postfix", "telnetd"] - - -[[repos.git]] -~~~~~~~~~~~~~ - -The ``[[repos.git]]`` entries are used to add files from a `git repository `_ -repository to the created image. The repository is cloned, the specified ``ref`` is checked out -and an rpm is created to install the files to a ``destination`` 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. - -To create an rpm named ``server-config-1.0-1.noarch.rpm`` you would add this to your blueprint:: - - [[repos.git]] - rpmname="server-config" - rpmversion="1.0" - rpmrelease="1" - summary="Setup files for server deployment" - repo="PATH OF GIT REPO TO CLONE" - ref="v1.0" - destination="/opt/server/" - -* rpmname: Name of the rpm to create, also used as the prefix name in the tar archive -* rpmversion: Version of the rpm, eg. "1.0.0" -* rpmrelease: Release of the rpm, eg. "1" -* summary: Summary string for the rpm -* repo: URL of the get repo to clone and create the archive from -* ref: Git reference to check out. eg. origin/branch-name, git tag, or git commit hash -* destination: Path to install the / of the git repo at when installing the rpm - -An rpm will be created with the contents of the git repository referenced, with the files -being installed under ``/opt/server/`` in this case. - -``ref`` can be any valid git reference for use with ``git archive``. eg. to use the head -of a branch set it to ``origin/branch-name``, a tag name, or a commit hash. - -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. - - -Adding Output Types -------------------- - -``livemedia-creator`` supports a large number of output types, and only some of -these are currently available via ``lorax-composer``. To add a new output type to -lorax-composer a kickstart file needs to be added to ``./share/composer/``. The -name of the kickstart is what will be used by the ``/compose/types`` route, and the -``compose_type`` field of the POST to start a compose. It also needs to have -code added to the :py:func:`pylorax.api.compose.compose_args` function. The -``_MAP`` entry in this function defines what lorax-composer will pass to -:py:func:`pylorax.installer.novirt_install` when it runs the compose. When the -compose is finished the output files need to be copied out of the build -directory (``/var/lib/lorax/composer/results//compose/``), -:py:func:`pylorax.api.compose.move_compose_results` handles this for each type. -You should move them instead of copying to save space. - -If the new output type does not have support in livemedia-creator it should be -added there first. This will make the output available to the widest number of -users. - -Example: Add partitioned disk support -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Partitioned disk support is something that livemedia-creator already supports -via the ``--make-disk`` cmdline argument. To add this to lorax-composer it -needs 3 things: - -* A ``partitioned-disk.ks`` file in ``./share/composer/`` -* A new entry in the _MAP in :py:func:`pylorax.api.compose.compose_args` -* Add a bit of code to :py:func:`pylorax.api.compose.move_compose_results` to move the disk image from - the compose directory to the results directory. - -The ``partitioned-disk.ks`` is pretty similar to the example minimal kickstart -in ``./docs/fedora-minimal.ks``. You should remove the ``url`` and ``repo`` -commands, they will be added by the compose process. Make sure the bootloader -packages are included in the ``%packages`` section at the end of the kickstart, -and you will want to leave off the ``%end`` so that the compose can append the -list of packages from the blueprint. - -The new ``_MAP`` entry should be a copy of one of the existing entries, but with ``make_disk`` set -to ``True``. Make sure that none of the other ``make_*`` options are ``True``. The ``image_name`` is -what the name of the final image will be. - -``move_compose_results()`` can be as simple as moving the output file into -the results directory, or it could do some post-processing on it. The end of -the function should always clean up the ``./compose/`` directory, removing any -unneeded extra files. This is especially true for the ``live-iso`` since it produces -the contents of the iso as well as the boot.iso itself. - -Package Sources ---------------- - -By default lorax-composer uses the host's configured repositories. It copies -the ``*.repo`` files from ``/etc/yum.repos.d/`` into -``/var/lib/lorax/composer/repos.d/`` at startup, these are immutable system -repositories and cannot be deleted or changed. If you want to add additional -repos you can put them into ``/var/lib/lorax/composer/repos.d/`` or use the -``/api/v0/projects/source/*`` API routes to create them. - -The new source can be added by doing a POST to the ``/api/v0/projects/source/new`` -route using JSON (with `Content-Type` header set to `application/json`) or TOML -(with it set to `text/x-toml`). The format of the source looks like this (in -TOML):: - - name = "custom-source-1" - url = "https://url/path/to/repository/" - type = "yum-baseurl" - proxy = "https://proxy-url/" - check_ssl = true - check_gpg = true - gpgkey_urls = ["https://url/path/to/gpg-key"] - -The ``proxy`` and ``gpgkey_urls`` entries are optional. All of the others are required. The supported -types for the urls are: - -* ``yum-baseurl`` is a URL to a yum repository. -* ``yum-mirrorlist`` is a URL for a mirrorlist. -* ``yum-metalink`` is a URL for a metalink. - -If ``check_ssl`` is true the https certificates must be valid. If they are self-signed you can either set -this to false, or add your Certificate Authority to the host system. - -If ``check_gpg`` is true the GPG key must either be installed on the host system, or ``gpgkey_urls`` -should point to it. - -You can edit an existing source (other than system sources), by doing a POST to the ``new`` route -with the new version of the source. It will overwrite the previous one. - -A list of existing sources is available from ``/api/v0/projects/source/list``, and detailed info -on a source can be retrieved with the ``/api/v0/projects/source/info/`` route. By default -it returns JSON but it can also return TOML if ``?format=toml`` is added to the request. - -Non-system sources can be deleted by doing a ``DELETE`` request to the -``/api/v0/projects/source/delete/`` route. - -The documentation for the source API routes can be `found here `_ - -The configured sources are used for all blueprint depsolve operations, and for composing images. -When adding additional sources you must make sure that the packages in the source do not -conflict with any other package sources, otherwise depsolving will fail. - -DVD ISO Package Source -~~~~~~~~~~~~~~~~~~~~~~ - -In some situations the system may want to *only* use a DVD iso as the package -source, not the repos from the network. ``lorax-composer`` and ``anaconda`` -understand ``file://`` URLs so you can mount an iso on the host, and replace the -system repo files with a configuration file pointing to the DVD. - -* Stop the ``lorax-composer.service`` if it is running -* Move the repo files in ``/etc/yum.repos.d/`` someplace safe -* Create a new ``iso.repo`` file in ``/etc/yum.repos.d/``:: - - [iso] - name=iso - baseurl=file:///mnt/iso/ - enabled=1 - gpgcheck=1 - gpgkey=file:///mnt/iso/RPM-GPG-KEY-redhat-release - -* Remove all the cached repo files from ``/var/lib/lorax/composer/repos/`` -* Restart the ``lorax-composer.service`` -* Check the output of ``composer-cli status show`` for any output specific depsolve errors. - For example, the DVD usually does not include ``grub2-efi-*-cdboot-*`` so the live-iso image - type will not be available. - -If you want to *add* the DVD source to the existing sources you can do that by -mounting the iso and creating a source file to point to it as described in the -`Package Sources`_ documentation. In that case there is no need to remove the other -sources from ``/etc/yum.repos.d/`` or clear the cached repos. +``lorax-composer`` has been replaced by the ``osbuild-composer`` WELDR API +server which implements more features (eg. ostree, image uploads, etc.) You +can still use ``composer-cli`` and ``cockpit-composer`` with +``osbuild-composer``. See the documentation or the `osbuild website +`_ for more information. diff --git a/docs/html/_sources/mkksiso.rst.txt b/docs/html/_sources/mkksiso.rst.txt index ad486002..f1222739 100644 --- a/docs/html/_sources/mkksiso.rst.txt +++ b/docs/html/_sources/mkksiso.rst.txt @@ -90,10 +90,11 @@ You can use the kickstart `liveimg command to install a pre-generated disk image or tar to the system the iso is booting on. -Create a disk image or tar with ``lorax-composer`` or ``livemedia-creator``, +Create a disk image or tar with ``osbuild-composer`` or ``livemedia-creator``, make sure the image includes tools expected by ``anaconda``, as well as the -kernel and bootloader support. In ``lorax-composer`` use the ``liveimg-tar`` -image type. If you plan to install it to a UEFI machine make sure to include +kernel and bootloader support. In ``osbuild-composer`` use the ``tar`` image +type and make sure to include the ``kernel``, ``grub2``, and ``grub2-tools`` +packages. If you plan to install it to a UEFI machine make sure to include ``grub2-efi`` and ``efibootmgr`` in the blueprint. Add the ``root.tar.xz`` file to the iso using ``--add /PATH/TO/ROOT.TAR.XZ``, diff --git a/docs/html/_sources/modules.rst.txt b/docs/html/_sources/modules.rst.txt index cc16b668..15b5f96f 100644 --- a/docs/html/_sources/modules.rst.txt +++ b/docs/html/_sources/modules.rst.txt @@ -5,5 +5,4 @@ src :maxdepth: 4 composer - lifted pylorax diff --git a/docs/html/_sources/pylorax.rst.txt b/docs/html/_sources/pylorax.rst.txt index 13d2907b..76c3adfe 100644 --- a/docs/html/_sources/pylorax.rst.txt +++ b/docs/html/_sources/pylorax.rst.txt @@ -1,14 +1,6 @@ pylorax package =============== -Subpackages ------------ - -.. toctree:: - :maxdepth: 4 - - pylorax.api - Submodules ---------- diff --git a/docs/html/_static/documentation_options.js b/docs/html/_static/documentation_options.js index 7829aa48..d7d6e486 100644 --- a/docs/html/_static/documentation_options.js +++ b/docs/html/_static/documentation_options.js @@ -1,6 +1,6 @@ var DOCUMENTATION_OPTIONS = { URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'), - VERSION: '34.0', + VERSION: '34.3', LANGUAGE: 'None', COLLAPSE_INDEX: false, BUILDER: 'html', diff --git a/docs/html/composer-cli.html b/docs/html/composer-cli.html index 5aa624ec..886a71aa 100644 --- a/docs/html/composer-cli.html +++ b/docs/html/composer-cli.html @@ -8,7 +8,7 @@ - composer-cli — Lorax 34.0 documentation + composer-cli — Lorax 34.3 documentation @@ -36,7 +36,7 @@ - + @@ -60,7 +60,7 @@
    - 34.0 + 34.3
    @@ -89,7 +89,6 @@
  • Before Lorax
  • Lorax
  • livemedia-creator
    • -
  • lorax-composer
  • composer-cli
    • composer-cli cmdline arguments
    • mkksiso
      • @@ -186,13 +202,11 @@

      composer-cli is an interactive tool for use with a WELDR API server, -managing blueprints, exploring available packages, and building new images. -lorax-composer <lorax-composer.html> and osbuild-composer -<https://osbuild.org> both implement compatible servers.

      +managing blueprints, exploring available packages, and building new images. As +of Fedora 34, osbuild-composer <https://osbuild.org> is the recommended +server.

      It requires the server to be installed on the local system, and the user -running it needs to be a member of the weldr group. They do not need to be -root, but all of the security precautions -apply.

      +running it needs to be a member of the weldr group.

      composer-cli cmdline arguments¶

      Lorax Composer commandline tool

      @@ -342,12 +356,12 @@ TO-COMMIT can be a commit hash, NEWEST, or WORKSPACE

      Edit a Blueprint¶

      Start out by listing the available blueprints using composer-cli blueprints list, pick one and save it to the local directory by running composer-cli -blueprints save http-server. If there are no blueprints available you can -copy one of the examples from the test suite.

      +blueprints save http-server.

      Edit the file (it will be saved with a .toml extension) and change the description, add a package or module to it. Send it back to the server by running composer-cli blueprints push http-server.toml. You can verify that it was saved by viewing the changelog - composer-cli blueprints changes http-server.

      +

      See the Example Blueprint for an example.

      Build an image¶

      @@ -384,9 +398,11 @@ by using composer-c with composer-cli upload start .... In order to access the service you need to pass authentication details to composer-cli using a TOML file, or reference a previously saved profile.

      -

      lorax-composer and osbuild-composer handle this differently, with -osbuild-composer you can currently only specify upload targets during the -compose process.

      +
      +

      Note

      +

      With osbuild-composer you can only specify upload targets during +the compose process.

      +

      Providers¶

      @@ -490,6 +506,309 @@ end with a failed state.

      --test=2 will cause a compose to start and then end with a finished state, without actually composing anything.

      +
      +

      Blueprint Reference¶

      +

      Blueprints are simple text files in TOML format that describe +which packages, and what versions, to install into the image. They can also define a limited set +of customizations to make to the final image.

      +

      A basic blueprint looks like this:

      +
      name = "base"
+description = "A base system with bash"
+version = "0.0.1"
+
+[[packages]]
+name = "bash"
+version = "4.4.*"
+
      +
      +

      The name field is the name of the blueprint. It can contain spaces, but they will be converted to - +when it is written to disk. It should be short and descriptive.

      +

      description can be a longer description of the blueprint, it is only used for display purposes.

      +

      version is a semver compatible version number. If +a new blueprint is uploaded with the same version the server will +automatically bump the PATCH level of the version. If the version +doesn't match it will be used as is. eg. Uploading a blueprint with version +set to 0.1.0 when the existing blueprint version is 0.0.1 will +result in the new blueprint being stored as version 0.1.0.

      +
      +

      [[packages]] and [[modules]]¶

      +

      These entries describe the package names and matching version glob to be installed into the image.

      +

      The names must match the names exactly, and the versions can be an exact match +or a filesystem-like glob of the version using * wildcards and ? +character matching.

      +
      +

      Note

      +

      Currently there are no differences between packages and modules +in osbuild-composer. Both are treated like an rpm package dependency.

      +
      +

      For example, to install tmux-2.9a and openssh-server-8.*, you would add +this to your blueprint:

      +
      [[packages]]
+name = "tmux"
+version = "2.9a"
+
+[[packages]]
+name = "openssh-server"
+version = "8.*"
+
      +
      +
      +
      +

      [[groups]]¶

      +

      The groups 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.

      +

      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.

      +

      For example, if you want to install the anaconda-tools group you would add this to your +blueprint:

      +
      [[groups]]
+name="anaconda-tools"
+
      +
      +

      groups is a TOML list, so each group needs to be listed separately, like packages but with +no version number.

      +
      +
      +

      Customizations¶

      +

      The [customizations] section can be used to configure the hostname of the final image. eg.:

      +
      [customizations]
+hostname = "baseimage"
+
      +
      +

      This is optional and may be left out to use the defaults.

      +
      +

      [customizations.kernel]¶

      +

      This allows you to append arguments to the bootloader's kernel commandline. This will not have any +effect on tar or ext4-filesystem images since they do not include a bootloader.

      +

      For example:

      +
      [customizations.kernel]
+append = "nosmt=force"
+
      +
      +
      +
      +

      [[customizations.sshkey]]¶

      +

      Set an existing user's ssh key in the final image:

      +
      [[customizations.sshkey]]
+user = "root"
+key = "PUBLIC SSH KEY"
+
      +
      +

      The key will be added to the user's authorized_keys file.

      +
      +

      Warning

      +

      key expects the entire content of ~/.ssh/id_rsa.pub

      +
      +
      +
      +

      [[customizations.user]]¶

      +

      Add a user to the image, and/or set their ssh key. +All fields for this section are optional except for the name, here is a complete example:

      +
      [[customizations.user]]
+name = "admin"
+description = "Administrator account"
+password = "$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31L..."
+key = "PUBLIC SSH KEY"
+home = "/srv/widget/"
+shell = "/usr/bin/bash"
+groups = ["widget", "users", "wheel"]
+uid = 1200
+gid = 1200
+
      +
      +

      If the password starts with $6$, $5$, or $2b$ it will be stored as +an encrypted password. Otherwise it will be treated as a plain text password.

      +
      +

      Warning

      +

      key expects the entire content of ~/.ssh/id_rsa.pub

      +
      +
      +
      +

      [[customizations.group]]¶

      +

      Add a group to the image. name is required and gid is optional:

      +
      [[customizations.group]]
+name = "widget"
+gid = 1130
+
      +
      +
      +
      +

      [customizations.timezone]¶

      +

      Customizing the timezone and the NTP servers to use for the system:

      +
      [customizations.timezone]
+timezone = "US/Eastern"
+ntpservers = ["0.north-america.pool.ntp.org", "1.north-america.pool.ntp.org"]
+
      +
      +

      The values supported by timezone can be listed by running timedatectl list-timezones.

      +

      If no timezone is setup the system will default to using UTC. The ntp servers are also +optional and will default to using the distribution defaults which are fine for most uses.

      +

      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.

      +
      +
      +

      [customizations.locale]¶

      +

      Customize the locale settings for the system:

      +
      [customizations.locale]
+languages = ["en_US.UTF-8"]
+keyboard = "us"
+
      +
      +

      The values supported by languages can be listed by running localectl list-locales from +the command line.

      +

      The values supported by keyboard can be listed by running localectl list-keymaps from +the command line.

      +

      Multiple languages can be added. The first one becomes the +primary, and the others are added as secondary. One or the other of languages +or keyboard must be included (or both) in the section.

      +
      +
      +

      [customizations.firewall]¶

      +

      By default the firewall blocks all access except for services that enable their ports explicitly, +like sshd. This command can be used to open other ports or services. Ports are configured using +the port:protocol format:

      +
      [customizations.firewall]
+ports = ["22:tcp", "80:tcp", "imap:tcp", "53:tcp", "53:udp"]
+
      +
      +

      Numeric ports, or their names from /etc/services can be used in the ports enabled/disabled lists.

      +

      The blueprint settings extend any existing settings in the image templates, so if sshd is +already enabled it will extend the list of ports with the ones listed by the blueprint.

      +

      If the distribution uses firewalld you can specify services listed by firewall-cmd --get-services +in a customizations.firewall.services section:

      +
      [customizations.firewall.services]
+enabled = ["ftp", "ntp", "dhcp"]
+disabled = ["telnet"]
+
      +
      +

      Remember that the firewall.services are different from the names in /etc/services.

      +

      Both are optional, if they are not used leave them out or set them to an empty list []. If you +only want the default firewall setup this section can be omitted from the blueprint.

      +

      NOTE: The Google and OpenStack templates explicitly disable the firewall for their environment. +This cannot be overridden by the blueprint.

      +
      +
      +

      [customizations.services]¶

      +

      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. ami requires +sshd, chronyd, and cloud-init. Without them the image will not +boot. Blueprint services are added to, not replacing, the list already in the +templates, if any.

      +

      The service names are systemd service units. You may specify any systemd unit +file accepted by systemctl enable eg. cockpit.socket:

      +
      [customizations.services]
+enabled = ["sshd", "cockpit.socket", "httpd"]
+disabled = ["postfix", "telnetd"]
+
      +
      +
      +
      [[repos.git]]¶
      +
      +

      Note

      +

      Currently osbuild-composer does not support repos.git

      +
      +

      The [[repos.git]] entries are used to add files from a git repository +repository to the created image. The repository is cloned, the specified ref is checked out +and an rpm is created to install the files to a destination 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.

      +

      To create an rpm named server-config-1.0-1.noarch.rpm you would add this to your blueprint:

      +
      [[repos.git]]
+rpmname="server-config"
+rpmversion="1.0"
+rpmrelease="1"
+summary="Setup files for server deployment"
+repo="PATH OF GIT REPO TO CLONE"
+ref="v1.0"
+destination="/opt/server/"
+
      +
      +
        +

      • rpmname: Name of the rpm to create, also used as the prefix name in the tar archive

        • +

      • rpmversion: Version of the rpm, eg. "1.0.0"

        • +

      • rpmrelease: Release of the rpm, eg. "1"

        • +

      • summary: Summary string for the rpm

        • +

      • repo: URL of the get repo to clone and create the archive from

        • +

      • ref: Git reference to check out. eg. origin/branch-name, git tag, or git commit hash

        • +

      • destination: Path to install the / of the git repo at when installing the rpm

        • +
      +

      An rpm will be created with the contents of the git repository referenced, with the files +being installed under /opt/server/ in this case.

      +

      ref can be any valid git reference for use with git archive. eg. to use the head +of a branch set it to origin/branch-name, a tag name, or a commit hash.

      +

      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.

      +
      +
      +
      +
      +
      +

      Example Blueprint¶

      +

      This example blueprint will install the tmux, git, and vim-enhanced +packages. It will set the root ssh key, add the widget and admin +users as well as a students group:

      +
      name = "example-custom-base"
+description = "A base system with customizations"
+version = "0.0.1"
+
+[[packages]]
+name = "tmux"
+version = "*"
+
+[[packages]]
+name = "git"
+version = "*"
+
+[[packages]]
+name = "vim-enhanced"
+version = "*"
+
+[customizations]
+hostname = "custombase"
+
+[[customizations.sshkey]]
+user = "root"
+key = "A SSH KEY FOR ROOT"
+
+[[customizations.user]]
+name = "widget"
+description = "Widget process user account"
+home = "/srv/widget/"
+shell = "/usr/bin/false"
+groups = ["dialout", "users"]
+
+[[customizations.user]]
+name = "admin"
+description = "Widget admin account"
+password = "$6$CHO2$3rN8eviE2t50lmVyBYihTgVRHcaecmeCk31LeOUleVK/R/aeWVHVZDi26zAH.o0ywBKH9Tc0/wm7sW/q39uyd1"
+home = "/srv/widget/"
+shell = "/usr/bin/bash"
+groups = ["widget", "users", "students"]
+uid = 1200
+
+[[customizations.user]]
+name = "plain"
+password = "simple plain password"
+
+[[customizations.user]]
+name = "bart"
+key = "SSH KEY FOR BART"
+groups = ["students"]
+
+[[customizations.group]]
+name = "widget"
+
+[[customizations.group]]
+name = "students"
+
      +
      +
      @@ -503,7 +822,7 @@ without actually composing anything.

      - + diff --git a/docs/html/composer.cli.html b/docs/html/composer.cli.html index eab3edfc..aa542a7f 100644 --- a/docs/html/composer.cli.html +++ b/docs/html/composer.cli.html @@ -8,7 +8,7 @@ - composer.cli package — Lorax 34.0 documentation + composer.cli package — Lorax 34.3 documentation @@ -35,7 +35,7 @@ - + @@ -60,7 +60,7 @@
      - 34.0 + 34.3
      @@ -89,7 +89,6 @@
    • Before Lorax
    • Lorax
    • livemedia-creator
      • -
    • lorax-composer
    • composer-cli
    • mkksiso
    • Product and Updates Images
      • @@ -105,7 +104,6 @@
    • Module contents
    • -
  • lifted package
  • pylorax package
    • @@ -1372,9 +1370,13 @@ include this extra information.

  • argtype (type) -- Type to use for checking the argument value

    • +
    Returns
    +

    (args, value)

    +
    +
    Return type
    +

    tuple

    +
    -

    :returns (args, value) -:rtype: tuple

    This removes the optional argument and value from the argument list, returns the new list, and the value of the argument.

    @@ -1457,7 +1459,7 @@ not to continue processing the results.