Merge branch 'main' into ignition-blueprint

osbuild-composer/src/SUMMARY.md

@@ -1,5 +1,6 @@
 # Summary
 
+- [Introduction](./introduction.md)
 - [User guide](./user-guide/user-guide.md)
   - [osbuild-composer description](./user-guide/osbuild-composer-description.md)
   - [Installation and configuration](./user-guide/installation.md)

osbuild-composer/src/blueprint-reference/blueprint-reference.md

@@ -191,11 +191,11 @@ Multiple languages can be added. The first one becomes the primary, and the othe
 
 ### Firewall
 
-By default the firewall blocks all access, except for services that enable their ports explicitly, like sshd. The following command can be used to open other ports or services. Ports are configured using the `port:protocol` format:
+By default the firewall blocks all access, except for services that enable their ports explicitly, like sshd. The following command can be used to open other ports or services. Ports are configured using the `port:protocol` format; port ranges are configured using `portA-portB:protocol` format:
 
 ```toml
 [customizations.firewall]
-ports = ["22:tcp", "80:tcp", "imap:tcp", "53:tcp", "53:udp"]
+ports = ["22:tcp", "80:tcp", "imap:tcp", "53:tcp", "53:udp", "30000-32767:tcp", "30000-32767:udp"]
 ```
 
 Numeric ports, or their names from `/etc/services` can be used in the ports enabled/disabled lists.
@@ -293,6 +293,8 @@ data = "Hello world!"
 - `group` is the group to set as the owner of the file. If not specified, the default is `root`. Can be specified as group name (string) or as group id (integer).
 - `data` is the plain text contents of the file. If not specified, the default is an empty file.
 
+Note that the `data` property can be specified in any of the ways supported by TOML. Some of them require escaping certain characters and others don't. Please refer to the [TOML specification](https://toml.io/en/v1.0.0#string) for more details.
+
 ### Ignition
 
 The `customizations.ignition` section allows users to provide [Ignition](https://coreos.github.io/ignition/) configuration files to be used in `edge-raw-image` and `edge-simplified-installer` images. Check the RHEL for Edge (`r4e`) [butane](https://coreos.github.io/butane/specs/) specification for a description of the supported configuration options.
@@ -365,11 +367,11 @@ In addition to the root mountpoint, `/`, the following `mountpoints` and their s
 
 ### OpenSCAP Support
 
-From `RHEL8.7` & `RHEL-9.1` support has been added for `OpenSCAP` build-time remediation. The blueprints accept two fields:
+From `RHEL 8.7` & `RHEL 9.1` support has been added for `OpenSCAP` build-time remediation. The blueprints accept two fields:
 - the `datastream` path to the remediation instructions
 - the `profile_id` of the desired security profile
 
-Please see [the OpenSCAP page]('../user-guide/oscap-remediation.md') for the list of available security profiles.
+Please see [the OpenSCAP page](../user-guide/oscap-remediation.md) for the list of available security profiles.
 
 ```toml
 [customizations.openscap]

osbuild-composer/src/introduction.md

@@ -0,0 +1,45 @@
+# Introduction
+
+OSBuild is comprised of many individual projects which work together to provide a wide range of features to build and assemble operating system artifacts. The graphical user interfaces can be found under the term [Image Builder](./introduction.md#image-builder) and provide access to the osbuild machinery. They integrate into existing operating system interfaces, including the **Cockpit** management console, the **cloud.redhat.com** customer services, as well as the classic linux **command-line**.
+
+The [Composer](./introduction.md#composer) project is the underlying system service that provides the APIs required by the multitude of user interfaces. It serves as arbiter between the specific requirements of the user interfaces and the general purpose functionality provided by [osbuild](./introduction.md#osbuild), the engine that drives the builds and assemblies of the individual artifacts.
+
+Users will find help for the graphical interfaces in the respective UI documentation of Image Builder. The Composer section contains help on deploying your own build services, or refining the blueprints of the operating system artifacts. Lastly, information on the osbuild tool sheds light on the inner workings, the system requirements, and the wide applicability of the engine and heart of OSBuild.
+
+## Image Builder
+
+The Image Builder user interfaces integrate into existing operating system user interfaces and extend them to support building operating system artifacts via the OSBuild tools. These interfaces are tightly coupled with their respective surrounding interfaces and often documented there. Followingly, a list of external user-interfaces and links to their respective documentation, followed by a list of user-interface documentation that is part of OSBuild itself.
+
+- **Cockpit Composer**: The web-based management console Cockpit comes bundled with a UI extension to build operating system artifacts. See the documentation of Cockpit Composer for information, or consult the Cockpit Guide for help on general Cockpit questions.
+
+- **CloudDot**: The Red Hat Customer Service Portal on cloud.redhat.com has built-in interfaces to the OSBuild functionality, allowing customers to build images and other artifacts on-demand. Consult the Red Hat Support Pages for help, or dive into the Image Builder Documentation to get more details on the underlying software.
+
+- **Command-line Interface**: With composer-cli there exists a linux command-line interface (CLI) to some of the functionality provided by OSBuild. The CLI is part of the Weldr project, a precursor of OSBuild.
+
+- **OSBuild User Documentation**
+  - [HOWTO: Image Builder + OSTree + Anaconda](https://www.osbuild.org/news/2020-06-01-how-to-ostree-anaconda.html)
+
+## Composer
+
+The system service OSBuild Composer provides APIs and services to build operating system images and other artifacts. It defines the blueprints of a wide range of images and a managed environment to execute the required build pipelines.
+
+The Composer service exports a large set of APIs, each tailored for a specific user-interface and use-case. Underneath, it converts all API requests to a uniform worker API which uses the osbuild machinery to execute the build pipelines.
+
+For high-level documentation and information on development, see its Project Pages @GitHub.
+
+- **OSBuild Composer Administrator Documentation**:
+  - [osbuild.org/guides](./)
+
+## osbuild
+
+The osbuild project is the heart of OSBuild. It defines a pipeline description to build arbitrary operating system artifacts out of many small and self-contained stages. Furthermore, it provides an execution engine that will consume a pipeline description, execute the pipeline, and provide the resulting image back to the user. The osbuild interfaces are meant to be used by machines, not humans. Therefore, access to osbuild resources should only be required if you plan to develop new osbuild frontends, debug osbuild failures on your own, or contribute to the osbuild development.
+
+For high-level documentation and information on development, see its Project Pages @GitHub.
+
+- **OSBuild System Documentation**:
+  - [MAN: osbuild-manifest.5](https://www.osbuild.org/man/osbuild-manifest.5)
+  - [MAN: osbuild.1](https://www.osbuild.org/man/osbuild.1)
+
+- **OSBuild Developer Documentation**:
+  - [Introducing RPMrepo](https://www.osbuild.org/news/2020-10-23-introducing-rpmrepo.html)
+  - [RPMrepo: RPM Repository Snapshots](https://www.osbuild.org/rpmrepo/)