diff --git a/docs/user-guide/00-introduction.md b/docs/user-guide/00-introduction.md
index 90bafc901b4..8634da8e289 100644
--- a/docs/user-guide/00-introduction.md
+++ b/docs/user-guide/00-introduction.md
@@ -23,43 +23,50 @@ Customizations are specifications for the image that are not packages. This incl
### Image Builder output formats
-Image Builder can create images in multiple output formats shown in the following table.
+Image Builder can create images in multiple output formats shown in the following table. Availability depends on the distribution; for the full per-distro catalog (including cloud RHUI/SAP/CVM variants and Fedora desktop/atomic types), see [Image descriptions](./09-image-descriptions/index.md). Type names can differ by distribution (for example Fedora uses `generic-vagrant-libvirt` while RHEL/CentOS use `vagrant-libvirt`); always check `image-builder list` for the distro you are building.
**Table 1. Image Builder output formats**
-| Name | CLI name | File extension | Description |
-|-----------------------------------|:------------------------------------------------------:|----------------|------------------------------------------------------------------------------------------------------|
-| QEMU Image | qcow2 | `.qcow2` | QCOW2 formatted disk image for use with QEMU/Libvirt. |
-| Disk Archive | tar | `.tar` | Archive of the root filesystem without any bootloader or partition table. |
-| Amazon Machine Image | ami | `.ami` | Disk image for use with AWS EC2. |
-| Microsoft Azure | vhd | `.vhd` | Disk image for use with Microsoft Azure. |
-| Google Cloud Platform | gce | `.tar.gz` | Disk image for use with Google Cloud Platform. |
-| VMware vSphere | vmdk | `.vmdk` | VMDK formatted disk image for use with VMware vSphere. |
-| VMware vSphere | ova | `.ova` | OVA formatted disk image for use with VMware vSphere. |
-| Openstack | openstack | `.qcow2` | QCOW2 formatted disk image for use with OpenStack. |
-| Edge/IoT[^1] Commit | edge-commit
iot-commit | `.tar` | OSTree commit archive. |
-| Edge/IoT[^1] Container | edge-container
iot-container | `.tar` | Web server container that embeds and serves an ostree repository with the given single commit. |
-| Edge/IoT[^1] Installer | edge-installer
iot-installer | `.iso` | OSTree-based Anaconda installer ISO for deploying IoT images. |
-| Edge/IoT[^1] Raw Image | edge-raw-image
iot-raw-image | `.raw.xz` | Compressed raw disk image for OSTree-based IoT devices. |
-| Edge/IoT[^1] Simplified Installer | edge-simplified-installer
iot-simplified-installer | `.iso` | OSTree-based installer ISO using coreos-installer for direct disk deployment using FIDO or ignition. |
-| Edge/IoT[^1] AMI | edge-ami
iot-ami | `.ami` | OSTree-based Amazon Machine Image tailored for IoT deployments on AWS EC2. |
+| Name | CLI name | File extension | Description |
+|-----------------------------------|:------------------------------------------------------:|----------------|------------------------------------------------------------------------------------------------------|
+| QEMU Image | qcow2 | `.qcow2` | QCOW2 formatted disk image for use with QEMU/Libvirt. |
+| Disk Archive | tar | `.tar` | Archive of the root filesystem without any bootloader or partition table. |
+| Amazon Machine Image | ami | `.ami` | Disk image for use with AWS EC2. |
+| Microsoft Azure | vhd | `.vhd` | Disk image for use with Microsoft Azure. |
+| Google Cloud Platform | gce | `.tar.gz` | Disk image for use with Google Cloud Platform. |
+| VMware vSphere | vmdk | `.vmdk` | VMDK formatted disk image for use with VMware vSphere. |
+| VMware vSphere | ova | `.ova` | OVA formatted disk image for use with VMware vSphere. |
+| Openstack | openstack | `.qcow2` | QCOW2 formatted disk image for use with OpenStack. |
+| Edge/IoT[^1] Commit | edge-commit
iot-commit | `.tar` | OSTree commit archive. |
+| Edge/IoT[^1] Container | edge-container
iot-container | `.tar` | Web server container that embeds and serves an ostree repository with the given single commit. |
+| Edge/IoT[^1] Installer | edge-installer
iot-installer | `.iso` | OSTree-based Anaconda installer ISO for deploying IoT images. |
+| Edge/IoT[^1] Raw Image | edge-raw-image
iot-raw-xz | `.raw.xz` | Compressed raw disk image for OSTree-based IoT devices. |
+| Edge/IoT[^1] Simplified Installer | edge-simplified-installer
iot-simplified-installer | `.iso` | OSTree-based installer ISO using coreos-installer for direct disk deployment using FIDO or ignition. |
+| Edge AMI | edge-ami | `.ami` | OSTree-based Amazon Machine Image tailored for IoT deployments on AWS EC2. |
| Edge vSphere | edge-vsphere | `.vmdk` | OSTree-based VMDK formatted disk image for IoT deployments on VMware vSphere. |
-| Image installer | image-installer | `.iso` | Anaconda ISO with an embedded pre-built OS archive. |
-| Live installer | live-installer | `.iso` | Anaconda ISO with a live operating system. |
-| Oracle Cloud Infrastructure Image | oci | `.qcow2` | QCOW2 formatted disk image for use with Oracle Cloud. This is identical to the qcow2 image. |
+| Image installer | image-installer | `.iso` | Anaconda ISO with an embedded pre-built OS archive. |
+| Live installer | workstation-live-installer | `.iso` | Anaconda ISO with a live operating system. |
+| Oracle Cloud Infrastructure Image | oci | `.qcow2` | QCOW2 formatted disk image for use with Oracle Cloud. This is identical to the qcow2 image. |
+| WSL | wsl | `.wsl` | Root filesystem archive for use with Windows Subsystem for Linux. |
+| Minimal raw | minimal-raw
minimal-raw-xz | `.raw` / `.raw.xz` | Raw disk image (optionally xz-compressed) for bare-metal or generic virtualization. |
+| PXE | pxe-tar-xz | `.tar.xz` | Kernel, initramfs, and rootfs archive for network (PXE) boot. |
+| Container | container
container-minimal | `.tar` | OCI container image tarball. |
+| Vagrant[^2] | vagrant-libvirt
vagrant-virtualbox
generic-vagrant-libvirt
generic-vagrant-virtualbox | `.box` | Vagrant box for libvirt or VirtualBox. |
+| Network installer | network-installer | `.iso` | Anaconda network install ISO. |
To check the supported types, run the command:
-Using the `image-builder` CLI:
+Using the `image-builder` CLI:
```
$ image-builder list
```
-Using the `composer-cli` CLI:
+Using the `composer-cli` CLI:
```
$ composer-cli compose types
```
[^1]: Edge is the variant for CentOS and RHEL, while it's called IoT on Fedora. Technically the output format is the same for both.
+[^2]: RHEL, CentOS, and similar use `vagrant-libvirt` / `vagrant-virtualbox`. Fedora's canonical names are `generic-vagrant-libvirt` / `generic-vagrant-virtualbox` (no short alias).
diff --git a/docs/user-guide/01-blueprint-reference.md b/docs/user-guide/01-blueprint-reference.md
index 12c1feacdda..b929d3d5bbe 100644
--- a/docs/user-guide/01-blueprint-reference.md
+++ b/docs/user-guide/01-blueprint-reference.md
@@ -79,7 +79,7 @@ Note that **osbuild-composer prior to version 100** didn't use a dot `.` to sepa
name = "tmux"
description = "tmux image with openssh"
version = "1.2.16"
-distro = "fedora-38"
+distro = "fedora-44"
[[packages]]
name = "tmux"
@@ -94,9 +94,7 @@ version = "*"
name = "tmux"
description = "tmux image with openssh"
version = "1.2.16"
-# for osbuild-composer version < 100
-# distro = "rhel-84"
-distro = "rhel-8.4"
+distro = "rhel-10.2"
[[packages]]
name = "tmux"
@@ -112,7 +110,7 @@ version = "*"
{
"image_name": "tmux",
"image_description": "tmux image with openssh",
- "distribution": "fedora-38",
+ "distribution": "fedora-44",
"customizations": {
"packages": ["tmux", "openssh-server"]
}
@@ -123,7 +121,7 @@ version = "*"
{
"image_name": "tmux",
"image_description": "tmux image with openssh",
- "distribution": "rhel-8.4",
+ "distribution": "rhel-10.2",
"customizations": {
"packages": ["tmux", "openssh-server"]
}
@@ -1366,6 +1364,9 @@ Supported modes (when the image type allows them):
- `lvm` — always LVM
- `btrfs` — always Btrfs for root (extra mountpoints become subvolumes; see [Partitioning](./07-partitioning.md))
+> :warning: **Note**
+> `partitioning_mode = "btrfs"` is **not supported on CentOS or RHEL** with the stock kernel. Use it on Fedora (and similar) distributions.
+
```toml
@@ -1395,7 +1396,7 @@ _See the section of the guide on [Partitioning](./07-partitioning.md) for more d
_See also the [Disk](#disk) section below for more advanced partitioning control._
-The blueprints can be extended to provide filesytem support. Currently the `mountpoint` and minimum partition `minsize` can be set. On `RHEL-8`, custom mountpoints are supported only since version `8.5`. For older `RHEL` versions, only the root mountpoint, `/`, is supported, the size argument being an alias for the image size.
+The blueprints can be extended to provide filesystem support. Currently the `mountpoint` and minimum partition `minsize` can be set. On `RHEL-8`, custom mountpoints are supported only since version `8.5`. For older `RHEL` versions, only the root mountpoint, `/`, is supported, the size argument being an alias for the image size.
@@ -1485,7 +1486,7 @@ The disk customizations are an alternative to the [filesystem](#filesystems) cus
The two customizations are incompatible with each other; you may use one or the other, but not both in the same blueprint.
-The examples below are illustrative but not comprehensive. The [Partitioning](./07-partitioning.md) guide should be consulted to understand all the ways in which this customization can be used.
+The examples below are illustrative but not comprehensive. The [Partitioning](./07-partitioning.md) guide should be consulted to understand all the ways in which this customization can be used, including advanced GPT/DOS partition-table fields such as `part_type`, `part_label`, and `part_uuid`.
@@ -1620,11 +1621,11 @@ The same mountpoint restrictions apply as described for [Filesystems](#filesyste
### OpenSCAP 🔵 🟤 {#openscap}
-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 (optional)
-- the `profile_id` of the desired security profile
+From `RHEL 8.7`, `RHEL 9.1`, and `RHEL 10` / CentOS Stream 10, support has been added for `OpenSCAP` build-time remediation. Blueprint fields:
-If the datastream parameter is not provided, `osbuild-composer` will now provide a sensible default based on the selected distro.
+- `datastream` — path to the remediation instructions (optional). If omitted, Image Builder / `osbuild-composer` picks a sensible default for the selected distro.
+- `profile_id` — ID of the desired security profile (required for remediation).
+- `policy_id` — (optional) UUID of a compliance policy. Puts the policy ID in the RHSM facts so instances registered to Insights are automatically connected to that compliance policy in the console (hosted / Insights use case; also accepted in on-premises blueprint TOML).
Please see [the OpenSCAP page](./03-oscap-remediation.md) for the list of available security profiles.
@@ -1637,6 +1638,7 @@ Building OpenSCAP hardened images for `ostree` based images not supported.
[customizations.openscap]
datastream = "/usr/share/xml/scap/ssg/content/ssg-rhel8-ds.xml"
profile_id = "xccdf_org.ssgproject.content_profile_cis"
+policy_id = "00000000-0000-0000-0000-000000000000" # optional — Insights compliance policy UUID
```
@@ -1644,7 +1646,8 @@ profile_id = "xccdf_org.ssgproject.content_profile_cis"
{
"customizations": {
"openscap": {
- "profile_id": "xccdf_org.ssgproject.content_profile_cis"
+ "profile_id": "xccdf_org.ssgproject.content_profile_cis",
+ "policy_id": "00000000-0000-0000-0000-000000000000"
}
}
}
diff --git a/docs/user-guide/02-repository-customizations.md b/docs/user-guide/02-repository-customizations.md
index 74b722ccc8f..0aad9d04d72 100644
--- a/docs/user-guide/02-repository-customizations.md
+++ b/docs/user-guide/02-repository-customizations.md
@@ -21,7 +21,13 @@ to use custom repositories for installing third-party packages, continue reading
## 2. Save repository configurations
In the second scenario, to make third-party repository configurations persistent and make the repositories available to users on the system, one would use the blueprint `custom repository`
configurations to enable this. The repository will be configured and saved to `/etc/yum.repos.d` as a `.repo` file. GPG keys are not imported at build time, but are imported when first
-installing a third-party package from the desired repository. You can find the blueprint reference for custom repositories [here](./01-blueprint-reference.md).
+installing a third-party package from the desired repository.
+
+Blueprint schema:
+
+- On-premises TOML: [`customizations.repositories`](./01-blueprint-reference.md#repositories)
+- Hosted JSON: `custom_repositories` (same section; see the hosted tab)
+- Related: optional [`customizations.dnf`](./01-blueprint-reference.md#dnf) for DNF configuration persisted on the image
## 3. Install a third-party package and save configurations
In this case it is necessary to use a combination of payload repositories and custom repositories in order to achieve the desired outcome. This will ensure that the package is installed during
diff --git a/docs/user-guide/03-oscap-remediation.md b/docs/user-guide/03-oscap-remediation.md
index 9f00a058f7c..cce02672d0b 100644
--- a/docs/user-guide/03-oscap-remediation.md
+++ b/docs/user-guide/03-oscap-remediation.md
@@ -1,7 +1,7 @@
# OpenSCAP Remediation
`osbuild-composer` provides the ability to build security hardened images using the [OpenSCAP] tool.
-This feature is available for `RHEL 8.7` (& above) and `RHEL 9.1` (& above).
+This feature is available for `RHEL 8.7` (& above), `RHEL 9.1` (& above), and `RHEL 10` / CentOS Stream 10.
[OpenSCAP]: https://github.com/OpenSCAP/openscap/blob/maint-1.3/docs/manual/manual.adoc
@@ -26,20 +26,20 @@ profile_id = "xccdf_org.ssgproject.content_profile_standard"
datastream = "/usr/share/xml/scap/ssg/content/ssg-fedora-ds.xml"
```
-`osbuild-composer` exposes to fields for the user to customize in the image blueprints:
-
- 1) The path to the `datastream` instructions. Usually in the `/usr/share/xml/scap/ssg/content/` directory
- 2) The `profile_id` for the desired security standard
- 3) Install `OpenSCAP` via this command: `dnf install scap-security-guide`
- 4) Use the command `oscap info /usr/share/xml/scap/ssg/content/.xml` to obtain more information such as the profile id to use
- 5) The `profile_id` field accepts both the long and short forms, for example, `cis` or `xccdf_org.ssgproject.content_profile_cis`.
-
-
+Blueprint OpenSCAP customizations accept these fields:
+- `datastream` — path to the datastream instructions (optional; usually under `/usr/share/xml/scap/ssg/content/`). If omitted, Image Builder picks a distro default.
+- `profile_id` — the desired security profile. Accepts both long and short forms, for example `cis` or `xccdf_org.ssgproject.content_profile_cis`.
+- `policy_id` — (optional, hosted / Insights) UUID of a compliance policy; see the [Blueprint Reference OpenSCAP section](./01-blueprint-reference.md#openscap).
+On the build host (or a system with `scap-security-guide` installed), you can discover profile IDs with:
+```
+dnf install scap-security-guide
+oscap info /usr/share/xml/scap/ssg/content/.xml
+```
-See the [Supported profiles](./03-oscap-remediation.md#supported-profiles) table for supported profiles.
+See the [Supported profiles](./03-oscap-remediation.md#supported-profiles) table for profiles Image Builder allows per distro family.
`osbuild-composer` will then generate the necessary configurations for the `osbuild` stage based on the user
customizations. Additionally, two packages will be added to the image, `openscap-scanner` (the `OpenSCAP` tool)
@@ -54,24 +54,30 @@ Building OpenSCAP hardened images for `ostree` based images not supported.
## Supported profiles
-The supported profiles are distro specific, see below:
-
-| | Fedora | RHEL 8.7^ | CS9/RHEL 9.1^ |
-|-----------------------------|--------|-----------|---------------|
-| ANSSI-BP-028 (enhanced) | | x | x |
-| ANSSI-BP-028 (high) | | x | x |
-| ANSSI-BP-028 (intermediary) | | x | x |
-| ANSSI-BP-028 (minimal) | | x | x |
-| CIS Level 2 - Server | | x | x |
-| CIS Level 1 - Server | | x | x |
-| CIS Level 1 - Workstation | | x | x |
-| CIS Level 2 - Workstation | | x | x |
-| CUI | | x | x |
-| Essential Eight | | x | x |
-| HIPAA | | x | x |
-| ISM Official | | x | x |
-| OSPP | x | x | x |
-| PCI-DSS | x | x | x |
-| Standard | x | | |
-| DISA STIG | | x | x |
-| DISA STIG with GUI | | x | x |
+The supported profiles are distro specific. The table below reflects Image Builder **allowlists** (from `image-builder` distro definitions). Column headers use the minors currently documented on this site for image descriptions; the `^` means that major line from the noted GA onward (where OpenSCAP remediations apply).
+
+| | Fedora | RHEL 8.10^ | CS9/RHEL 9.8^ | CS10/RHEL 10.2^ |
+|-----------------------------|:------:|:----------:|:-------------:|:---------------:|
+| ANSSI-BP-028 (enhanced) | | x | x | x |
+| ANSSI-BP-028 (high) | | x | x | x |
+| ANSSI-BP-028 (intermediary) | | x | x | x |
+| ANSSI-BP-028 (minimal) | | x | x | x |
+| BSI | | | x | x |
+| CCN (advanced) | | | x | |
+| CCN (basic) | | | x | |
+| CCN (intermediate) | | | x | |
+| CIS Level 2 - Server | | x | x | x |
+| CIS Level 1 - Server | | x | x | x |
+| CIS Level 1 - Workstation | | x | x | x |
+| CIS Level 2 - Workstation | | x | x | x |
+| CUI | | x | x | |
+| Essential Eight | | x | x | x |
+| HIPAA | | x | x | x |
+| ISM Official | | x | x | x |
+| ISM Official (Secret) | | | | x |
+| ISM Official (Top Secret) | | | | x |
+| OSPP | x | x | x | x |
+| PCI-DSS | x | x | x | x |
+| Standard | x | | | |
+| DISA STIG | | x | x | x |
+| DISA STIG with GUI | | x | x | x |
diff --git a/docs/user-guide/07-partitioning.md b/docs/user-guide/07-partitioning.md
index b67700a7380..498dcd87db9 100644
--- a/docs/user-guide/07-partitioning.md
+++ b/docs/user-guide/07-partitioning.md
@@ -29,7 +29,7 @@ The partitioning mode controls how the partition table is modified from the imag
- `raw` will not convert any partition to LVM or Btrfs.
- `lvm` will always convert the partition that contains the root mountpoint `/` to an LVM Volume Group and create a root Logical Volume. Any extra mountpoints, except `/boot`, will be added to the Volume Group as new Logical Volumes.
-- `btrfs` will convert the partition that contains the root mountpoint `/` to a Btrfs volume and create a root subvolume. Any extra mountpoints, except `/boot`, will be added to the Btrfs volume as new Btrfs subvolumes.
+- `btrfs` will convert the partition that contains the root mountpoint `/` to a Btrfs volume and create a root subvolume. Any extra mountpoints, except `/boot`, will be added to the Btrfs volume as new Btrfs subvolumes. **Not supported on CentOS or RHEL** with the stock kernel (use Fedora); see [Partitioning mode](01-blueprint-reference.md#partitioning-mode).
- `auto-lvm` is the default mode and will convert a raw partition table to an LVM-based one if and only if new mountpoints are defined in the [filesystems customization](01-blueprint-reference.md#filesystems). See also the [Mountpoints](#mountpoints) section below.
#### Mountpoints