RHDL Documentation

Version: 0.4.0

🚀 Quick Start

Welcome to the Red Hat DownLoader (RHDL) documentation.

RHDL is a command-line tool that enables Red Hat partners to download various versions of Red Hat Enterprise Linux (RHEL) for local use.

🛡️ Note: RHDL is intended for Red Hat partners only. If you're not a partner yet, visit Red Hat Connect to join.

📦 Install the RHDL CLI

Make sure you have Python 3 installed, then run:

python3 -m pip install --user rhdl

This installs the rhdl CLI into your user environment.

🔐 Configure Authentification

To use RHDL, you’ll need a service account with access credentials.

🤖 Create a Service Account

Go to the RHDL Service Accounts page.
Create a new service account.
Copy the Access Key and Secret Key.

🔑 Authenticate with RHDL

Use the CLI to configure credentials:

rhdl login
RHDL Access Key [None]: <your-access-key>
RHDL Secret Key [None]: <your-secret-key>

This will save your credentials to:

~/.config/rhdl/credentials

🧪 Alternative: Use Environment Variables

If you prefer not to store credentials in a file:

export RHDL_ACCESS_KEY=<your-access-key>
export RHDL_SECRET_KEY=<your-secret-key>

📋 List Available RHEL Versions

Before downloading a compose, you can list all available RHEL versions:

rhdl version-list

This displays a table of available RHEL versions:

+----------------+
| RHEL version   |
|----------------|
| RHEL-10.2      |
| RHEL-10.1      |
| RHEL-10.0      |
| RHEL-9.8       |
| ...            |
| RHEL-8.2       |
+----------------+

JSON Output Format

For programmatic use, you can output the version list in JSON format:

rhdl version-list --format json

You can then process the output with tools like jq:

rhdl version-list --format json | jq -r ".[0]"

Example output:

{
  "name": "RHEL-10.2",
  "major_version": 10,
  "minor_version": 2
}

⬇️ Download a RHEL Compose

By default, RHDL will attempt to download a compose matching the provided compose_id.

rhdl download RHEL-10.0.0-20260101.0

If RHDL doesn't find a compose with an exact match, it will download the latest available compose whose name starts with the search term.

rhdl download RHEL-10

You can list all available components on the ui

⚙️ Command Options

🔧 Default Options

When no custom flags are provided:

rhdl download RHEL-9.4

This is equivalent to:

--destination="."
--include=".composeinfo"
--include="metadata/*"
--include="AppStream/x86_64/os/*"
--include="BaseOS/x86_64/os/*"
--exclude="*"

This will create a RHEL-9.4 folder in the current directory and include the AppStream and BaseOS variants for the x86_64 architecture.

📁 Custom Destination

By default, RHDL creates a subdirectory with the compose name. You can specify a different parent directory:

rhdl download RHEL-9.4 --destination /tmp/repo
# Downloads to: /tmp/repo/RHEL-9.4/

To download directly into a directory without creating a subdirectory, use the --flat flag:

rhdl download RHEL-9.4 --destination /tmp/repo --flat
# Downloads to: /tmp/repo/ without creating RHEL-9.4 subdirectory

rhdl download RHEL-9.4 --flat
# Downloads to current directory without creating RHEL-9.4 subdirectory

🔄 Overwrite Existing Destination

By default, RHDL will stop if the destination folder already exists to prevent accidental data loss:

rhdl download RHEL-9.4
# Error: Destination folder already exists: ./RHEL-9.4

To force the download and overwrite existing files, use the --force or -f flag:

rhdl download RHEL-9.4 --force
# Forces download to ./RHEL-9.4 even if it exists

rhdl download RHEL-9.4 -d /tmp/repo -f
# Forces download to /tmp/repo/RHEL-9.4 even if it exists

🏗️ Architecture & Variant Selection

RHDL allows you to select specific architectures and variants to download.

Architecture Selection

By default, RHDL downloads the x86_64 architecture. You can specify different architectures using the --arch flag:

Single architecture:

rhdl download RHEL-10 --arch aarch64

Multiple architectures (comma-separated):

rhdl download RHEL-10 --arch x86_64,aarch64

Multiple architectures (repeated flags):

rhdl download RHEL-10 --arch x86_64 --arch aarch64

Common architectures include: x86_64, aarch64, ppc64le, s390x

Variant Selection

By default, RHDL downloads the AppStream and BaseOS variants. You can specify different variants using the --variant flag:

Single variant:

rhdl download RHEL-10 --variant AppStream

Multiple variants (comma-separated):

rhdl download RHEL-10 --variant AppStream,BaseOS,CRB

Multiple variants (repeated flags):

rhdl download RHEL-10 --variant AppStream --variant RT

Available variants include:

AppStream - Application Stream repository
BaseOS - Base Operating System
CRB - CodeReady Builder
HighAvailability - High Availability Add-On
NFV - Network Functions Virtualization
RT - Real Time
SAP - SAP Solutions
SAPHANA - SAP HANA
unified - Unified repository

🐛 Debug Symbols & Source Code

Debug Symbols

To include debug symbols in your download, use the --with-debug-symbols flag (or its shorter alias --with-debug):

rhdl download RHEL-10 --with-debug-symbols

This will download both the regular packages and debug symbols. Example:

AppStream/x86_64/os/* (regular packages)
AppStream/x86_64/debug/* (debug symbols)
BaseOS/x86_64/os/*
BaseOS/x86_64/debug/*

Short form:

rhdl download RHEL-10 --with-debug

Source Code

To include source RPMs, use the --with-source flag:

rhdl download RHEL-10 --with-source

This will download source tree packages in addition to binary packages. Example:

AppStream/x86_64/os/*
AppStream/source/tree/* (source RPMs)
BaseOS/x86_64/os/*
BaseOS/source/tree/*

Combine both:

rhdl download RHEL-10 --with-debug --with-source

🎯 Fine-Grained Includes & Excludes

To limit the download to specific parts of the compose, use --include and --exclude.

Example: download only kernel RPMs with sources:

rhdl download RHEL-10.0 \
  --include="BaseOS/source/tree/Packages/kernel*" \
  --exclude="*"

ℹ️ How it works: RHDL evaluates include/exclude patterns in order. The first match determines the result:

Match an exclude → skip the file
Match an include → download the file
No match → file is downloaded

Pattern Syntax

RHDL supports two types of patterns:

1. Shell-style wildcards (default):

* matches any sequence of characters

Example with shell-style patterns:

rhdl download RHEL-9.4 \
  --include="BaseOS/x86_64/os/Packages/*" \
  --exclude="*"

2. Regex patterns: When a pattern contains (, ), or |, it's automatically treated as a regex pattern:

(AppStream|BaseOS) matches either AppStream or BaseOS
(x86_64|s390x|ppc64le) matches any of the listed architectures

Example with regex patterns:

rhdl download RHEL-9.4 \
  --include="(AppStream|BaseOS)/(x86_64|s390x)/os/Packages/*" \
  --exclude="*"

Comma-Separated Patterns

You can specify multiple patterns in a single --include or --exclude flag by separating them with commas:

rhdl download RHEL-9.4 \
  --include="AppStream/x86_64/os/*,BaseOS/x86_64/os/*" \
  --exclude="*"

This is equivalent to:

rhdl download RHEL-9.4 \
  --include="AppStream/x86_64/os/*" \
  --include="BaseOS/x86_64/os/*" \
  --exclude="*"

🏷️ Tags & Channels

⚠️ Breaking change in v0.3.0

The --tag option no longer has a default value. Starting from version 0.3.0, a new --channel option has been introduced to filter composes by channel. If --tag is not specified, no tag-based filtering is applied. Users are encouraged to use --channel instead of --tag when filtering composes by channel.

Migration:

Before v0.3.0: rhdl download RHEL-10 (implicitly used --tag milestone)

From v0.3.0: rhdl download RHEL-10 (returns the latest available compose, no implicit tag filtering)

Channels

Channels allow you to filter the stream of composes, reducing the number of results returned.
By default, RHDL will download the most recent compose unless you specify a different channel.

To select a different channel, use the --channel flag:

# Get candidate composes
rhdl download RHEL-10 --channel candidate

# Get milestone composes
rhdl download RHEL-10 --channel milestone

Note: If you specify an unknown channel, it will be ignored and no channel filtering will be applied.

🌐 Using a Proxy

Set environment variables if you're behind a proxy:

export HTTP_PROXY=http://your.proxy.example.org
export HTTPS_PROXY=https://your.proxy.example.org

📊 Logging and Verbosity

⚠️ New in v0.4.0

RHDL now uses a structured logging system with configurable log levels. By default, informational messages are displayed on stderr, while functional output (like JSON data) goes to stdout.

Log Levels

Control the amount of logging information with the --log-level option:

rhdl --log-level=debug download RHEL-10
rhdl --log-level=info download RHEL-10    # Default
rhdl --log-level=warn download RHEL-10
rhdl --log-level=error download RHEL-10

Available log levels:

debug - Detailed diagnostic information including file downloads, retries, and internal operations
info - General informational messages about the download progress (default)
warn - Warning messages about potential issues
error - Only error messages

Default Behavior

By default (info level), you'll see:

Component being downloaded
File list download progress
Individual file download progress
Disk space information

Quiet Operation

For minimal output, use the error level:

rhdl --log-level=error download RHEL-10

This will only show errors, allowing you to redirect functional output cleanly:

rhdl --log-level=error version-list --format json > versions.json

Debug Mode

For troubleshooting, use debug level to see detailed information:

rhdl --log-level=debug download RHEL-10

This shows:

All info-level messages
Retry attempts with delays
Detailed network operations
File system operations

Output Separation

RHDL follows UNIX conventions:

Logs → stderr (controlled by --log-level)
Functional output → stdout (e.g., JSON from version-list, tables)

This allows clean output redirection:

# Capture only the JSON output, suppress logs
rhdl version-list --format json > versions.json

# Capture logs separately from data
rhdl version-list --format json > versions.json 2> logs.txt

# Suppress all logs
rhdl download RHEL-10 2>/dev/null

📄 License

Licensed under the Apache License 2.0

🆘 Help & Troubleshooting

Check the version and get available commands:

rhdl --version
rhdl --help

Make sure you're using the latest version if you encounter issues.

If you still need help, please send us an email at distributed-ci@redhat.com.