Skip to content

Repository configuration

Synopsis

Family Repository definitions Signing keys
Debian/Ubuntu /etc/apt/sources.list.d/*.sources (deb822), /etc/apt/sources.list.d/*.list and /etc/apt/sources.list (one-line) Files named by Signed-By, usually in /usr/share/keyrings/ or /etc/apt/keyrings/; /etc/apt/trusted.gpg.d/ for keys trusted for every repository
RHEL/Alma/Rocky /etc/yum.repos.d/*.repo Files named by gpgkey, usually in /etc/pki/rpm-gpg/; imported into the RPM database
Arch Sections of /etc/pacman.conf, with server lists in /etc/pacman.d/mirrorlist The pacman keyring in /etc/pacman.d/gnupg/, managed with pacman-key
Gentoo /etc/portage/repos.conf (ebuild repositories) and /etc/portage/binrepos.conf (binary package hosts), each a file or a directory of files Ebuild repositories: the file named by sync-openpgp-key-path; binary hosts: the keyring in /etc/portage/gnupg/

Description

A repository definition tells the package manager where to download package indexes and packages from, whether and how to verify their signatures, and how to rank the repository against the others. Changes take effect at the next metadata refresh: apt update, dnf makecache (or the next dnf command once the cache expires), pacman -Syu, or emaint sync on Gentoo.

Checked against apt 3.0.3 on Debian 13 and 3.2.0 on Ubuntu 26.04, dnf 4.20.0 on AlmaLinux 10.2 and Rocky Linux 10.2, pacman 7.1.0 on Arch Linux and Portage 3.0.83 on Gentoo (November 2026), and against the files these systems install.

Debian and Ubuntu: sources files

APT reads /etc/apt/sources.list and every file in /etc/apt/sources.list.d/ ending in .list (one-line format) or .sources (deb822 format). Debian 13 and Ubuntu 26.04 configure their own repositories in deb822 files: debian.sources and ubuntu.sources. apt modernize-sources converts .list files to .sources files.

deb822 format

A .sources file contains one or more stanzas separated by blank lines; each stanza can describe several suites and components at once.

Types: deb deb-src
URIs: https://deb.debian.org/debian
Suites: trixie trixie-updates
Components: main
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
Field Value Meaning
Types deb, deb-src Binary packages, source packages, or both
URIs One or more URIs Base URL of the repository. Supported schemes include http, https, file, cdrom and mirror+file (a local file listing mirrors, as used by Debian's cloud images)
Suites Suite or codename, e.g. trixie, resolute-security Directory under dists/. A value ending in / denotes a flat repository, which has no Components
Components e.g. main contrib non-free non-free-firmware (Debian), main restricted universe multiverse (Ubuntu) Sections of the suite to use
Signed-By Path to a key file, or a key block given inline Keys allowed to sign this repository's InRelease or Release.gpg. Keys listed here are used for this stanza only
Architectures e.g. amd64 Restrict downloads to these architectures
Enabled yes (default), no Turns the stanza off without deleting it
Check-Valid-Until yes (default), no Whether to enforce the Valid-Until date of the Release file
Trusted yes, no yes disables signature verification for the stanza

One-line format

deb [signed-by=/etc/apt/keyrings/example.asc arch=amd64] https://packages.example.com/debian stable main

deb or deb-src, optional options in square brackets (such as signed-by=, arch= and trusted=, with several values separated by commas), the URI, the suite, then the components. Each line describes one type, one URI and one suite.

Signing keys

Location Used for
/usr/share/keyrings/ Keys installed by packages, such as debian-archive-keyring and ubuntu-keyring
/etc/apt/keyrings/ Keys installed by the administrator. Used only where a Signed-By field names them
/etc/apt/trusted.gpg.d/ Keys trusted for every repository without a Signed-By field

Key files are OpenPGP certificates, either binary (.gpg, .pgp) or ASCII-armoured (.asc). Debian 13's apt verifies signatures with sqv (Sequoia), Ubuntu 26.04's with gpgv.

Priorities

Files in /etc/apt/preferences.d/ (format described in apt_preferences(5)) assign priorities to versions by package and origin:

Package: *
Pin: origin packages.example.com
Pin-Priority: 100
Pin form Matches
origin <HOST> Repositories served from that host name
release o=<ORIGIN>,a=<ARCHIVE>,n=<CODENAME>,l=<LABEL>,c=<COMPONENT> Fields of the repository's Release file
version <VERSION> Package versions, with * wildcards
Priority Effect
1000 and above Installed even if it means a downgrade
990 Default for the target release (APT::Default-Release)
500 Default for ordinary repositories
100 Installed version; also repositories marked NotAutomatic: yes and ButAutomaticUpgrades: yes, such as Debian backports
1 Repositories marked NotAutomatic: yes, such as Debian experimental
Below 0 Never installed

apt-cache policy shows the priority of every repository and, with a package name, of every version of that package.

RHEL, AlmaLinux and Rocky Linux: .repo files

dnf reads every file in /etc/yum.repos.d/ ending in .repo, and repository sections in /etc/dnf/dnf.conf. Each file contains one or more sections, one per repository; the section name is the repository ID.

[baseos]
name=AlmaLinux $releasever - BaseOS
mirrorlist=https://mirrors.almalinux.org/mirrorlist/$releasever/baseos
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-AlmaLinux-10
Option Default Meaning
name Human-readable name
baseurl One or more URLs of the repository (the directory containing repodata/)
mirrorlist URL of a list of baseurl values
metalink URL of a metalink document listing mirrors and metadata checksums
enabled 1 Whether the repository is used
gpgcheck From [main] (1 in the dnf.conf of RHEL and its rebuilds) Verify the signature of every package
repo_gpgcheck 0 Verify the signature of the repository metadata (repodata/repomd.xml.asc). The keys for this check are stored per repository, separately from the RPM database
gpgkey URLs (file://, https://) of the keys allowed to sign; imported into the RPM database on first use, after confirmation
priority 99 Lower numbers win when several repositories offer the same package
cost 1000 Relative cost of downloading; lower is preferred among repositories with equal priority
includepkgs Only these packages (comma-separated, globs allowed) are taken from the repository
excludepkgs (also exclude) These packages are ignored in the repository
metadata_expire 48h Age after which metadata is refreshed (seconds, or with m, h, d; -1 never)
skip_if_unavailable From [main] (False in the dnf.conf of RHEL and its rebuilds) Continue without the repository if it can't be reached
module_hotfixes 0 Make packages available even when they belong to a disabled or filtered module

Variables expand in values: $releasever (for example 10), $basearch (for example x86_64), $arch, and custom variables defined in files in /etc/dnf/vars/ (the file name is the variable name, its content the value).

Managing repositories

Command Effect
dnf repolist --all List repositories and whether they're enabled
dnf repoinfo <REPO> Show the configuration and state of a repository
dnf config-manager --set-enabled <REPO> Set enabled=1 in the repository's file
dnf config-manager --set-disabled <REPO> Set enabled=0
dnf config-manager --add-repo <URL> Download a .repo file into /etc/yum.repos.d/, or create one from a baseurl
dnf --enablerepo=<REPO>, --disablerepo=<REPO>, --repo=<REPO> Change the enabled repositories for one command only

dnf config-manager is part of dnf-plugins-core.

Signing keys

Key files are ASCII-armoured OpenPGP certificates, conventionally in /etc/pki/rpm-gpg/. Once imported, each key is an entry in the RPM database named gpg-pubkey-<KEYID>-<CREATED>, where <KEYID> is the last eight hexadecimal digits of the key's fingerprint in lower case and <CREATED> its creation time in hexadecimal. The RPM database's keys are trusted for packages from any repository.

Command Effect
rpm --import <FILE or URL> Import a key
rpm -q gpg-pubkey --qf '%{NAME}-%{VERSION}-%{RELEASE}\t%{SUMMARY}\n' List imported keys
rpm -e gpg-pubkey-<KEYID> Remove an imported key
rpm -K <FILE>.rpm Check a package file's digests and signature

Arch: pacman.conf and the mirror list

/etc/pacman.conf is an INI-style file with an [options] section followed by one section per repository. The repositories are searched in the order they appear: when several offer a package with the same name, the first one wins regardless of version.

[options]
HoldPkg     = pacman glibc
Architecture = auto
SigLevel    = Required DatabaseOptional
LocalFileSigLevel = Optional

[core]
Include = /etc/pacman.d/mirrorlist

[extra]
Include = /etc/pacman.d/mirrorlist

Options that affect repositories

Option Section Meaning
Server = <URL> Repository A server for the repository. $repo and $arch in the URL expand to the repository name and architecture. Several Server lines are tried in order
Include = <FILE> Any Read further options, typically Server lines, from a file
SigLevel [options] or repository Signature requirements; a repository's value overrides [options]
LocalFileSigLevel, RemoteFileSigLevel [options] Signature requirements for pacman -U with a local file or a URL
Usage Repository Any of Sync, Search, Install, Upgrade, or All (default)
CacheDir [options] Package cache directory (default /var/cache/pacman/pkg/)
IgnorePkg, IgnoreGroup [options] Packages or groups that pacman -Syu doesn't upgrade
ParallelDownloads [options] Number of simultaneous downloads (5 in the default file)

SigLevel values

Value Meaning
Never No signature checks
Optional Check signatures if present; unsigned files are accepted
Required Signatures are required, and must be valid
TrustedOnly (default), TrustAll Whether a valid signature must also come from a fully trusted key, or any known key

Prefixing a value with Package or Database (for example DatabaseOptional) applies it only to packages or only to repository databases. The default, Required DatabaseOptional, requires signed packages and accepts unsigned databases; Arch's official repository databases aren't signed.

Mirror list

/etc/pacman.d/mirrorlist contains Server lines for the official repositories, grouped by country, for example:

## Worldwide
#Server = https://geo.mirror.pkgbuild.com/$repo/os/$arch

Only uncommented lines are used, in order; in the file as the pacman-mirrorlist package installs it, every line is commented out. Installation media and tools such as reflector write a list with working mirrors uncommented. When the package is updated after you have edited the file, the new version is written as mirrorlist.pacnew. A mirror list can also point at a date in the Arch Linux Archive (https://archive.archlinux.org/repos/<YYYY>/<MM>/<DD>/$repo/os/$arch) to install packages as they were on that day.

Signing keys

pacman verifies signatures against its own keyring in /etc/pacman.d/gnupg/, separate from any user's GnuPG keyring.

Command Effect
pacman-key --init Create the keyring and a local signing key
pacman-key --populate Add and trust the keys from the installed keyring packages (archlinux-keyring)
pacman-key --add <FILE> Add a key from a file
pacman-key --recv-keys <FINGERPRINT> Fetch a key from a key server
pacman-key --lsign-key <FINGERPRINT> Locally sign a key, which makes it trusted
pacman-key --list-keys List the keys
pacman-key --delete <FINGERPRINT> Remove a key

A locally signed key is trusted for packages and databases from every repository.

Gentoo: repos.conf and binrepos.conf

Ebuild repositories: repos.conf

Portage reads /usr/share/portage/config/repos.conf, which defines the Gentoo repository, and then /etc/portage/repos.conf, which can be a single file or a directory of files and overrides or adds to it. Each section is a repository; [DEFAULT] sets main-repo.

[DEFAULT]
main-repo = gentoo

[gentoo]
location = /var/db/repos/gentoo
sync-type = rsync
sync-uri = rsync://rsync.gentoo.org/gentoo-portage
auto-sync = yes
sync-rsync-verify-metamanifest = yes
sync-openpgp-key-path = /usr/share/openpgp-keys/gentoo-release.asc
Option Meaning
location Directory where the repository is stored
sync-type Synchronisation method: rsync, git, webrsync (as emerge-webrsync), mercurial, svn, cvs, zipfile
sync-uri Where to synchronise from
auto-sync Whether emaint sync --auto and emerge --sync synchronise the repository (yes by default)
priority Higher numbers take precedence when a package exists in several repositories
sync-rsync-verify-metamanifest For rsync: verify the repository's signed top-level Manifest with gemato
sync-webrsync-verify-signature For webrsync: verify the signature of the downloaded snapshot
sync-git-verify-commit-signature For git: require a valid signature, by a key in sync-openpgp-key-path, on the newest commit
sync-openpgp-key-path File containing the OpenPGP keys allowed to sign the repository
sync-openpgp-key-refresh Whether to refresh those keys before each sync, so that a revoked key is noticed: yes (the default, from the web key directory, then the key server), wkd, keyserver, no (with a warning on each sync) or false-nowarn; with refresh on, the sync fails if the refresh fails
sync-openpgp-keyserver Key server used to refresh those keys
sync-depth For git and other version control systems: clone depth; default 1 (only the newest commit), 0 for full history

Packages from one repository can be addressed with the ::<REPO> suffix in atoms, for example */*::example in /etc/portage/package.mask masks every package from the repository example. eselect repository (package app-eselect/eselect-repository, not installed by default) adds and removes repositories listed in Gentoo's repository registry by writing entries in /etc/portage/repos.conf/.

Binary package hosts: binrepos.conf

/etc/portage/binrepos.conf (a file or a directory) lists binary package hosts, used by emerge --getbinpkg. The stage 3 archives install /etc/portage/binrepos.conf/gentoo.conf for Gentoo's official host:

[gentoo]
priority = 1
sync-uri = https://distfiles.gentoo.org/releases/amd64/binpackages/23.0/x86-64
location = /var/cache/binhost/gentoo
verify-signature = true
Option Meaning
sync-uri Base URL of the binary package host (the directory containing Packages)
priority Higher numbers take precedence between binary hosts
location Local directory for packages downloaded from this host
verify-signature Require valid signatures on binary packages from this host

PORTAGE_BINHOST in make.conf is the older way of listing binary hosts.

Signing keys

Repository type Keys
The Gentoo ebuild repository /usr/share/openpgp-keys/gentoo-release.asc, installed by sec-keys/openpgp-keys-gentoo-release
Other ebuild repositories The file named by sync-openpgp-key-path in the repository's section
Binary package hosts The GnuPG home directory /etc/portage/gnupg/, shared by all hosts; getuto (package app-portage/getuto) creates it and imports the Gentoo release keys

FEATURES="binpkg-request-signature" in make.conf, set in the stage 3 archives, refuses binary packages without a valid signature.

Files

Path Family Purpose
/etc/apt/sources.list.d/ Debian/Ubuntu Repository definitions
/etc/apt/preferences.d/ Debian/Ubuntu Pinning and priorities
/etc/apt/keyrings/ Debian/Ubuntu Administrator-installed keys for Signed-By
/etc/apt/auth.conf.d/ Debian/Ubuntu Credentials for repositories that need a login
/etc/yum.repos.d/ RHEL/Alma/Rocky Repository definitions
/etc/dnf/dnf.conf RHEL/Alma/Rocky Global options ([main]), defaults for every repository
/etc/dnf/vars/ RHEL/Alma/Rocky Custom variables for repository definitions
/etc/pki/rpm-gpg/ RHEL/Alma/Rocky Signing key files
/etc/pacman.conf Arch Options and repository sections
/etc/pacman.d/mirrorlist Arch Servers for the official repositories
/etc/pacman.d/gnupg/ Arch The keyring of pacman
/etc/portage/repos.conf Gentoo Ebuild repository definitions
/etc/portage/binrepos.conf Gentoo Binary package hosts
/etc/portage/gnupg/ Gentoo Keyring for binary package signatures
/etc/portage/make.conf Gentoo GENTOO_MIRRORS (source download mirrors), FEATURES

See also