# Global Variables Reference

> Complete reference for global configuration in images/variables.yml

---

LLMS index: [llms.txt](/llms.txt) | Full content: [llms-full.txt](/llms-full.txt)

---

Complete reference for global configuration settings that apply to all
container images.

## Overview

The `images/variables.yml` file contains global configuration that applies to
all container images in the repository. These settings define project-wide
defaults, security parameters, and variant-specific behavior.

**Location:** `images/variables.yml` (in the containers repository root)

**Scope:** All images inherit these settings unless overridden in
image-specific `properties.yml`

## Configuration Reference

### cpe

- **Type**: String (CPE 2.2 formatted string)
- **Default**: `"cpe:/a:redhat:hummingbird:1"`
- **Description**: Common Platform Enumeration (CPE) identifier for all
  Hummingbird containers.
- **Usage**: Automatically added as a label to all generated container images
  and passed to `inject-source-info` during the build process.
- **Format**: CPE 2.2 URI format: `cpe:/part:vendor:product:version`

### default_user

- **Type**: String (numeric UID)
- **Default**: `"65532"`
- **Description**: The default unprivileged user ID that all containers run as.
- **Usage**: Referenced by the `{{ set_user() }}` macro when `user: default` is specified
  (or when `user:` is omitted, as `default` is the default value).
- **Value**: `65532` is chosen as a high, non-conflicting UID that:
  - Avoids conflicts with system users (typically < 1000)
  - Avoids conflicts with regular users (typically 1000-60000)

### default_distros

- **Type**: Array of strings
- **Default**: `["rawhide", "hummingbird"]`
- **Description**: Defines the distribution variants (distros) for which images
  are built. Each distro represents a different base package source.
- **Directory Structure**: Images are organized as `images/<name>/<distro>/<variant>/`
- **Common Values**:
  - `rawhide` - Uses Fedora Rawhide repositories only
  - `hummingbird` - Uses both Fedora Rawhide and Hummingbird repositories
- **Usage**: Scripts iterate over distros and variants to find all image
  variants to build. Each distro/variant combination produces a separate
  container image.
- **See Also**: [default_variant_repos](#default_variant_repos) for repository
  configuration per distro

### default_variants

- **Type**: Array of strings
- **Default**: `["default", "builder"]`
- **Description**: Defines the default set of variants to generate for each
  image within each distro when not explicitly specified in the image's
  `properties.yml`.
- **Directory Structure**: Variants are subdirectories within each distro:
  `images/<name>/<distro>/<variant>/`
- **Common Values**:
  - `default` - The minimal runtime variant
  - `builder` - Extended variant with build tools and package managers
- **Extending**: Images can use `additional_variants` in `properties.yml` to add
  extra variants while keeping the defaults (preferred approach)
- **Override**: Images can specify `variants` in `properties.yml` to replace
  these defaults entirely (use when you need to exclude default variants)
- **See Also**: [Image Configuration Reference - variants][variants-field]

### default_rpm_packages

- **Type**: Object with variant names as keys, arrays of package names as
  values
- **Default**:

   ```yaml
   default_rpm_packages:
     builder:
       - bash
       - dnf5
       - shadow-utils
   ```

- **Description**: Defines packages that are automatically included in specific
  variants across all images. These are added in addition to packages defined
  in image-specific `properties.yml`.
- **Variants**: Currently only `builder` is defined, but other variants can be
  added
- **Usage**: Use this to provide variant-specific packages that should be
  available in all images using that variant. For example, builder variants
  include package management tools for development workflows.

### default_variant_repos

- **Type**: Object with distro names as keys, arrays of repository filenames
  as values
- **Default**:

  ```yaml
  default_variant_repos:
    rawhide:
      - fedora-44.repo
    hummingbird:
      - fedora-44.repo
      - hummingbird.repo
  ```

- **Description**: Defines which yum repositories each distro uses by default
  for package installation and lockfile generation. The Rawhide distro uses
  the latest branched Fedora development repo, while Hummingbird uses a
  stable Fedora release plus the Hummingbird package repository.
- **Repository Files**: References files in the `yum-repos/` directory
- **Usage**: This allows different distros to use different package sources.
  The `hummingbird` distro includes additional repositories that provide
  Hummingbird-specific packages.
- **Override**: Image-specific `additional_repos` in `properties.yml` are
  appended to the distro-specific repos
- **See Also**: [Image Configuration Reference - additional_repos][additional_repos]

### oscap

- **Type**: Object
- **Default**:

  ```yaml
  oscap:
    enabled: true
    profiles:
      cis: true
      stig:
        variants:
          - "*fips*"
    exclude_rules:
      - id: xccdf_org.ssgproject.content_rule_root_path_no_dot
        reason: "False positive: environmentvariable58 probe requires /proc
          which is unavailable in offline chroot scanning"
  ```

- **Description**: Global defaults for OpenSCAP compliance scanning. Scanning
  is enabled by default (`enabled: true`). Images can opt out by setting
  `enabled: false` in their `properties.yml`.
- **Fields**:
  - `enabled` - Whether compliance scanning is active (overridden per image)
  - `profiles` - Which compliance profiles run per variant. Each profile can
    be `true` (all variants), `false` (disabled), or `{variants: [...]}` with
    glob patterns. Default: CIS for all variants, STIG for FIPS variants.
  - `exclude_rules` - Global rule exclusions applied to all oscap-enabled
    images. Image-specific exclusions in `properties.yml` are concatenated
    with these (not replaced).
- **Merge Behavior**: When an image overrides `oscap` fields:
  - `enabled` (scalar) is replaced by the image value
  - `profiles` (dict) is recursively merged, so an image can override
    individual profiles without affecting others
  - `exclude_rules` (list) is concatenated, so image rules are added after
    global rules
- **See Also**: [Image Configuration Reference - Compliance Scanning][oscap-config]

### readme_targets

- **Type**: Object with target names as keys, configuration objects as values
- **Default**: See the actual file

- **Description**: Defines target-specific configuration for generating multiple
  README files from a single template. Each target represents a different
  build/distribution channel (e.g., Hummingbird project vs Red Hat product).
- **Target Configuration Fields**:
  - `filename` - Output filename for this target's README
  - `registry` - Container registry URL for image references
  - `product_name` - Full product name for documentation
  - `product_name_short` - Short product name for headings and titles
  - `doc_base_url` - Base URL for documentation links
- **Usage**: Templates access these values via `{{ readme_targets[target].registry }}`
  and similar expressions. The build system generates one README file per target
  from the same `README.md.j2` template.
- **See Also**: [Image Pipeline - README Generation][readme-generation]

## Next Steps

- [Image Configuration Reference][image-config] - Per-image configuration
- [Image Variants][image-variants] - Understanding variant types
- [Adding Images][adding-images] - How to add a new container image

[additional_repos]: https://hummingbird-project.io/l/image-configuration-reference#additional_repos
[image-config]: https://hummingbird-project.io/l/image-configuration-reference
[image-variants]: https://hummingbird-project.io/l/image-variants
[adding-images]: https://hummingbird-project.io/l/adding-images
[variants-field]: https://hummingbird-project.io/l/image-configuration-reference#variants
[readme-generation]: https://hummingbird-project.io/l/image-pipeline/#readme-generation
[oscap-config]: https://hummingbird-project.io/l/image-configuration-reference#compliance-scanning