Changing Rocky Linux Repository to a Custom Mirror
Point Rocky Linux DNF repositories at a custom mirror by editing the repo files safely, with cautions to avoid breaking it.
Core Principle
The strategy involves:
Backup Existing Configuration: Always save your current repository files so you can easily revert if needed.
Identify Mirror Structure: Determine the exact path structure (e.g., capitalization, presence of /os/) of the custom mirror for BaseOS, AppStream, and extras.
Create New Repository File: Configure a new .repo file with the custom mirror’s details.
Verify & Clean: Confirm dnf can use the new mirror and clean its cache.
Preparation
Before you begin, gather the following information and ensure you have the necessary components:
Rocky Linux Host: Your Rocky Linux server.
Root/Sudo Access: You will need sudo or direct root access for file modifications.
Custom Mirror URL: The base URL of the mirror you wish to use (e.g., https://rocky-linux-asia-southeast2.production.gcp.mirrors.ctrliq.cloud/pub/rocky).
Internet Connectivity: Ensure your server has active internet access to reach the mirror.
Find a Custom Mirror URL
Use the official Rocky Linux MirrorManager to find a mirror closest to your server’s location:
Mark this down as YOUR_ARCHITECTURE (e.g., x86_64, aarch64).
Confirm GPG Key Path:
Verify the existence of your Rocky Linux GPG key. It’s usually RPM-GPG-KEY-Rocky-X where X is your major version.
ls -l /etc/pki/rpm-gpg/RPM-GPG-KEY-Rocky-YOUR_ROCKY_VERSION
Mark this down as YOUR_GPG_KEY_FILE (e.g., /etc/pki/rpm-gpg/RPM-GPG-KEY-Rocky-9).
If this file is missing, you may need to install the appropriate rocky-release package or manually place the GPG key.
Explore the Custom Mirror’s Structure
This is a critical step as mirror structures vary. You need to understand how the mirror organizes BaseOS, AppStream, and extras for your specific YOUR_ROCKY_VERSION and YOUR_ARCHITECTURE.
Open in Browser: Navigate to your mirror’s base URL in a web browser, followed by YOUR_ROCKY_VERSION.
Identify Repository Directories: Look for directories like BaseOS/, AppStream/, extras/, etc. Pay close attention to capitalization (e.g., extras vs. Extras).
Check for /os/ subdirectory: For each main repository (e.g., BaseOS), click into it, then into YOUR_ARCHITECTURE/ (e.g., x86_64/). Observe if there’s an os/ subdirectory containing repodata/.
Example 1 (requires /os/):YOUR_MIRROR_BASE/YOUR_ROCKY_VERSION/BaseOS/YOUR_ARCHITECTURE/os/repodata/
Example 2 (no /os/):YOUR_MIRROR_BASE/YOUR_ROCKY_VERSION/BaseOS/YOUR_ARCHITECTURE/repodata/
Mark down the full, correct baseurl path for each desired repository. These will be used in your new .repo file.
Mark this down as YOUR_BACKUP_DIR (e.g., /etc/yum.repos.d/backup_20250910103000). This is where your original repository files will be moved.
3. Backup and Remove Existing Repository Files
This step moves all existing .repo files out of the active DNF configuration directory, ensuring a clean slate for your new custom mirror.
sudo mv /etc/yum.repos.d/*.repo YOUR_BACKUP_DIR/
Verify the files have moved, and /etc/yum.repos.d/ is now clean:
ls -l /etc/yum.repos.d/ls -l YOUR_BACKUP_DIR/
/etc/yum.repos.d/ should ideally now only contain the YOUR_BACKUP_DIR itself, not any .repo files directly.
4. Create the New Custom Repository File
Now, create a new .repo file using the specific URLs and GPG key path you identified earlier.
sudo vi /etc/yum.repos.d/custom-mirror.repo
Paste the following content, carefully replacing the placeholder URLs and file paths with your actual identified mirror paths and GPG key path:
[baseos]name=Rocky Linux $releasever - BaseOS - Custom Mirrorbaseurl=YOUR_BASEOS_MIRROR_URLgpgcheck=1enabled=1gpgkey=file://YOUR_GPG_KEY_FILEmetadata_expire=6h[appstream]name=Rocky Linux $releasever - AppStream - Custom Mirrorbaseurl=YOUR_APPSTREAM_MIRROR_URLgpgcheck=1enabled=1gpgkey=file://YOUR_GPG_KEY_FILEmetadata_expire=6h[extras]name=Rocky Linux $releasever - Extras - Custom Mirrorbaseurl=YOUR_EXTRAS_MIRROR_URLgpgcheck=1enabled=1gpgkey=file://YOUR_GPG_KEY_FILEmetadata_expire=6h# --- Optional Repositories (uncomment and verify paths if needed) ---# Check your mirror's structure for these. Adjust BaseOS/AppStream/extras# capitalization and the presence of '/os/' as necessary.#[powertools]#name=Rocky Linux $releasever - PowerTools - Custom Mirror#baseurl=YOUR_MIRROR_BASE_URL/$releasever/PowerTools/$basearch/os/ # Example path; adjust as needed#gpgcheck=1#enabled=0#gpgkey=file://YOUR_GPG_KEY_FILE#metadata_expire=6h#[resilientstorage]#name=Rocky Linux $releasever - ResilientStorage - Custom Mirror#baseurl=YOUR_MIRROR_BASE_URL/$releasever/ResilientStorage/$basearch/os/ # Example path; adjust as needed#gpgcheck=1#enabled=0#gpgkey=file://YOUR_GPG_KEY_FILE#metadata_expire=6h
Remember to replace:
YOUR_BASEOS_MIRROR_URL
YOUR_APPSTREAM_MIRROR_URL
YOUR_EXTRAS_MIRROR_URL
YOUR_GPG_KEY_FILE
If including optional repos, YOUR_MIRROR_BASE_URL with the beginning of your mirror path.
5. Clean DNF Cache
This forces DNF to re-read all repository configurations and download new metadata from your configured mirror.
sudo dnf clean all
6. Verify New Repository Configuration (CRITICAL STEP)
It’s crucial to confirm that DNF recognizes and can successfully access your new custom mirror.
sudo dnf repolist
You should see your new “Custom Mirror” repositories listed (e.g., “Rocky Linux 9 - BaseOS - Custom Mirror”).
Look carefully for any Error: messages. If you see errors like “Failed to download metadata” or “repomd.xml parser error,” it indicates an issue with the baseurl paths in your custom-mirror.repo file.
Now, attempt to check for updates. This performs a more thorough test by trying to download actual package metadata.
sudo dnf update --refresh
This command should execute without errors. If it fails or shows repository-related errors, immediately stop and follow the “Recovery Procedure” below.
If it lists available updates, it means the mirror is working correctly. You can then choose to apply the updates or not.
Recovery Procedure (If DNF Breaks)
If dnf update or dnf repolist fails catastrophically after these changes (e.g., “Error: Cannot find a valid baseurl for repo”, “metadata download failed”), follow these steps:
Access Your Rocky Linux Host: Use SSH or direct console access.
Open Command Shell: Get a root shell.
Restore Original Repository Configuration:
# Rename the problematic custom configuration filesudo mv /etc/yum.repos.d/custom-mirror.repo /etc/yum.repos.d/custom-mirror.repo.bad# Move your original working backup files back into the active DNF directory# Replace YOUR_BACKUP_DIR with the actual backup directory namesudo mv YOUR_BACKUP_DIR/*.repo /etc/yum.repos.d/# Clean DNF cache to pick up the original filessudo dnf clean all
Verify Access:
sudo dnf repolistsudo dnf update --refresh
This should now work with your original, default repositories.
Troubleshoot: Carefully review your custom mirror URL, its observed directory structure, and the paths you entered in your custom-mirror.repo file. Pay extremely close attention to capitalization and the presence/absence of /os/ in the paths. Correct any errors, then retry the configuration steps.