Loading...

VONDS ©

Lab 121: Configure DNF Repositories (RHEL)

Back to Lab Index

Audit enabled DNF repositories, validate repo definitions under /etc/yum.repos.d , and add a new .repo file safely. Confirm metadata health with dnf makecache , then disable a broken repo cleanly without deleting evidence.

packages repos troubleshooting rhel

Scenario

A RHEL-like server was cloned into a lab network and package installs are failing. The repo configuration may be incomplete, or a custom repo was added incorrectly. You need to audit what is enabled, confirm repo definitions on disk, add a repo file safely, validate metadata, then disable the broken repo cleanly.

Operator context

Repo failures can block patching and incident response. Treat repo files as configuration artifacts: back up before changes, validate repodata, and disable cleanly so you can restore service without losing context.

Objective

  • List enabled repositories and inspect a repo’s details.
  • Audit repo definition files under /etc/yum.repos.d .
  • Back up an existing repo file before changes.
  • Create a new .repo file with a valid repo id.
  • Validate repodata and caching behavior with dnf makecache .
  • Disable a broken repo without deleting the file.
  • Clean metadata and confirm the repo is no longer enabled.

Concepts

  • DNF consumes repository definitions from /etc/yum.repos.d/*.repo and treats each bracketed section as a repo id.
  • Repo health is primarily a metadata problem. If DNF cannot fetch repodata/repomd.xml , installs and updates will stall.
  • Disable broken repos before deleting anything. Preserving repo files keeps evidence for root cause and rollback.
  • Cache behavior matters. After repo changes, clean metadata so you are not validating against stale repodata.
  • Use targeted repo inspection ( dnf repoinfo ) to confirm baseurls and enablement state before you troubleshoot higher layers.

Walkthrough

Step 1 : List enabled repositories.
Command 
dnf repolist enabled

This is the fastest baseline check when installs fail. If expected repos are missing or disabled, nothing downstream will work. 

repo id                      repo name
appstream                    Rocky Linux 9 - AppStream
baseos                       Rocky Linux 9 - BaseOS
extras                       Rocky Linux 9 - Extras
Step 2 : Confirm repo definition files on disk.
Command 
ls -1 /etc/yum.repos.d

Repos are defined by .repo files in this directory. Missing files often explains missing repos. 

rocky.repo
rocky-addons.repo
Step 3 : Back up a repo file before changes.
Command 
sudo cp /etc/yum.repos.d/rocky.repo /etc/yum.repos.d/rocky.repo.bak

This is your safety net. If a repo change breaks installs, restore quickly and keep troubleshooting with known-good configuration. 

Backup created: /etc/yum.repos.d/rocky.repo.bak
Step 4 : Inspect details for one enabled repo (BaseOS).
Command 
dnf repoinfo baseos

Confirm the baseurl and whether the repo is enabled. A bad URL usually turns into metadata errors. 

Repo-id            : baseos
Repo-name          : Rocky Linux 9 - BaseOS
Repo-baseurl       : https://download.rockylinux.org/pub/rocky/9/BaseOS/x86_64/os/
Repo-enabled       : yes
Step 5 : Add a custom repo file under /etc/yum.repos.d ( custom.repo ).
Command 
sudo vim /etc/yum.repos.d/custom.repo

A repo file must include a repo id in brackets and a baseurl . This lab uses a deliberately broken URL so you can recognize the failure mode. 

[custom-tools]
name=Custom Tools Repo
baseurl=https://repo.example.lab/rhel/9/x86_64/
enabled=1
gpgcheck=0
Step 6 : Verify the repo file is readable and structured correctly.
Command 
sudo cat /etc/yum.repos.d/custom.repo

You want to see the bracketed repo id and the URL. Typos here become metadata failures later.

Step 7 : Build metadata cache (validate repo access).
Command 
sudo dnf makecache

This forces DNF to read repo configuration and attempt to fetch repodata/repomd.xml . A 404 usually means the baseurl is wrong or the repo is not structured correctly. 

Custom Tools Repo                                0.0  B/s |   0  B     00:00
Errors during downloading metadata for repository 'custom-tools':
  - Status code: 404 for https://repo.example.lab/rhel/9/x86_64/repodata/repomd.xml
Step 8 : Disable the custom repo without deleting the file.
Command 
sudo dnf config-manager --set-disabled custom-tools

Disabling keeps the configuration on disk for review, while immediately unblocking package operations. 

Repository 'custom-tools' is disabled.
Step 9 : Clean metadata after disabling the repo.
Command 
sudo dnf clean metadata

This removes cached metadata so you can rebuild cleanly and confirm the error no longer appears. 

0 files removed
Step 10 : Confirm the custom repo is not enabled.
Command 
dnf repolist enabled

Verification is the final step. You should see only expected repos enabled. 

repo id                      repo name
appstream                    Rocky Linux 9 - AppStream
baseos                       Rocky Linux 9 - BaseOS
extras                       Rocky Linux 9 - Extras
(custom-tools is disabled)

Common breakpoints

dnf repolist shows no enabled repos

If you have no enabled repos, package operations will fail across the board. Confirm repo files exist in /etc/yum.repos.d and that expected sections are set to enabled=1 .

repomd.xml download errors (404 or timeout)

A 404 usually means the baseurl path is wrong or the repo is not laid out correctly. Timeouts usually indicate DNS, routing, proxy, or firewall issues between the host and the repo endpoint.

config-manager command not found

If dnf config-manager is unavailable, the plugin package may not be installed on your distro. Install the appropriate plugin package, or disable the repo by editing the repo file and setting enabled=0 .

metadata errors persist after disabling the repo

Cached metadata may still reference the repo. Run dnf clean metadata and retry dnf makecache to confirm you are validating against a clean state.

Cleanup checklist

Your cleanup is confirming the system is back to a known-good repo state and the broken repo is disabled but preserved on disk for review.

Commands 
dnf repolist enabled
sudo dnf clean metadata
sudo dnf makecache
Success signal

Metadata builds without errors, and dnf repolist enabled shows only the expected repos.

Reference

  • ls -1 /etc/yum.repos.d : Lists repo definition files present on disk.
  • cp /etc/yum.repos.d/<file> /etc/yum.repos.d/<file>.bak : Creates a backup of a repo file before changes.
  • vim /etc/yum.repos.d/<name>.repo : Creates or edits a repo definition file.
  • cat /etc/yum.repos.d/<name>.repo : Validates a repo file is readable and contains expected keys.
  • dnf repolist enabled : Shows repositories currently enabled.
  • dnf repoinfo <repoid> : Shows repository details (baseurl, enabled state, etc.).
  • dnf makecache : Builds repository metadata cache to validate repo access.
  • dnf config-manager --set-disabled <repoid> : Disables a repo without deleting the repo file.
    • --set-disabled : Marks the repo as disabled.
  • dnf clean metadata : Removes cached metadata after repo changes.