Pinning sources in Debian
Proceed with Caution
Debian discourages the use of pinning to set preferences for package repositories, because the practice can have disastrous results. We take a closer look.
Pinning is the black art of Debian and its derivative distributions. Using pinning, you can set your preferences for which package repository to use, either for all installations or upgrades, or for a specific set of packages. Officially, however, Debian discourages pinning, because it can prevent package upgrades or even corrupt an entire system if used carelessly.
Debian, as you may know, uses three main repositories [1]. These are Stable, Testing, and Unstable, also known by their release names, which are currently Jessie, Stretch, and Sid – all characters from the Toy Story movies. A new package enters Debian in Unstable, and, when it meets certain requirements, moves to Testing. When a general release is made, the package moves to Stable. Between releases, StableUpdates and Backports are used to help keep Stable up to date with borrowings from Testing. Debian derivatives like Ubuntu organize repositories by other criteria but are still likely to have some repositories that are more stable or otherwise preferred.
However, both Debian's and Debian derivatives' main repositories are divided into sections based on licensing. The main section contains free-licensed packages, including core system components. By contrast, contrib contains free-licensed packages that depend on proprietary applications, while non-free contains proprietary packages. Debian installs with only main enabled, although contrib and non-free can be enabled by editing /etc/apt/sources.list
and then running apt-get update
.
The reason Debian discourages pinning is that it disrupts the repository system's careful arrangement of repositories by package quality – which can be disastrous at times. For example, when systemd was in Unstable, installing the packages on an otherwise Stable system slowed performance and limited the available display resolutions. These problems persisted for months, with no solution except a complete reinstall. Such problems are especially likely to occur in the months before a general release, when developers are concentrating on perfecting the packages in Testing to prepare for their move into the new Stable repository and often neglecting Unstable. They are also far more likely with core components, such as Linux kernels or desktop environments that have numerous essential dependencies.
Using third-party repositories can sometimes cause similar problems. Similarly, pinning can add unfree packages to an otherwise free-licensed system.
All the same, pinning remains popular. Debian can take a long time between releases, and some users will always want the most up-to-date versions of applications. Moreover, once set up, pinning is more convenient than alternatives such as constantly commenting and uncommenting lines in /etc/apt/sources.list
. Fortunately, by keeping informed about Debian development and taking a few precautions, pinning can be used with minimum risk – although some risk is likely to remain.
Getting Priorities Straight
Pinning sets priorities for packages in the repositories listed in files in /etc/apt
, such as sources.list
, or else those at a particular URL (Figure 1). If you want to borrow from a repository, you must first add it to the sources for the system and make sure that the entry is not commented out and then run apt-get update
. Otherwise, pinning has no effect.
By default, Debian assigns all repositories and gives each of the main repositories section an equal weight of 500 (Figure 2), preferring none of them (see below). You can check the current priorities on a system by running apt-cache policy
. To read the priority for a particular package, run apt-cache policy PACKAGE
.
Changing priorities means creating a preference file. In the past, all priorities were listed in /etc/apt/preferences
, with each priority setting in a stanza separated from the others by a line above and below. In the last few years, though, Debian and its derivatives have used individual files in the /etc/apt/preferences.d
directory (Figure 3). These individual files often use a .pref
extension, although any file in preferences.d
is read in setting priorities.
The structure for defining a preference can begin with an Explanation line for adding comments, although in practice this line is rarely used. More often, the structure consists of three lines. The first line, Package
, lists the package affected. The first line accepts regular expressions, so an asterisk (*) sets the priority for an entire repository – something that can be dangerous to do – while /WORD/
applies to any package that contains the enclosed word.
For safety, you are better off specifying an entire package or set of packages. For example, if you want the latest packages for the solitaire game pysolfc, you might complete the first line with *pysolfc*
. For a package with numerous dependencies, such as a desktop environment, you might have to choose the regular expressions carefully, although probably dependencies would drag in any other files not covered by them – something you definitely will want to check. The most common first line is:
Package: *
Pin, the second line, usually defines the package source by defining the archive (a=
), version (v=
), release name (n=
), and/or section component (c=
). A private repository can be defined with label (l=
). These building blocks can be combined in a comma-separated list, so that the line
Pin: release a=unstable,c=main,v-8.6
would apply to the main section of Unstable in Debian's 8.6 release. Less commonly, origin URL refers to a mirror site, or origin " "
to the local system. Refer to the sources.list
file to check that you have identified a source properly.
The third line is Pin-Priority. Its working is simple: The package source with the highest number is used first. If it is not available for some reason, the package will be installed – if possible – from the source with the next highest possibility. Table 1 lists the effect of each priority. A sample third line would be:
Table 1
Priority Settings
Setting | Effect |
---|---|
More than 1000 |
Version is installed even if it means downgrading the package version. Can be useful for fixing broken packages. |
990-1000 |
Version is installed even if not from the target release, unless the installed version is more recent. |
500-989 |
Version is installed unless the target release has a version or the installed version is most recent. This is the default priority for Debian. |
100-499 |
Version is installed unless another version exists in another repository or the installed version is more recent. |
0-99 |
Version is only installed if no other version is already installed. |
Less than 0 |
Prevents the version from being installed. Useful when you suspect a version may cause problems. |
Pin-Priority: 500
Priorities can be used in a number of ways beside the obvious. For example, problems with dependencies can sometimes be fixed by setting priorities to a number over a thousand, so that you can downgrade packages to what they once were. Similarly, a cautious administrator could set priorities so that the Stable has a priority of 1000, and everything else has a negative priority, so that even if a user with the right privileges adds another source, those sources will never be used in preference to Stable (Figure 4).
However you set source priorities, you always need to be cautious, because dependencies can lead to unexpected results. You should also be aware that, if a source is unavailable for some line, the source with the next highest priority will be used, which can sometimes lead to a broken package. In my experience, the safest way to use pinning is to assign a priority to the fewest number of packages possible. If that requires more thought and more .pref
files, it should also cause fewer problems.
Using Pinning
When you have set priorities, run apt-get update
to enable them. Before adding or upgrading packages, you should check the descriptions of the packages involved. Take special note of their dependencies: Generally, the more dependencies a package has, or the more core components are among its dependencies, the more borrowing from Testing, Unstable, or third parties is likely to cause problems.
Another precaution to use with pinning is to run apt-get
first with the -s
or --simulate
option. This option tells you what the result of your action will be but makes no changes to your system. The more complicated an action, the more sensible using this option becomes.
Pinning does not work automatically – only when you specify. It can be used with one of two command structures. The first example is:
apt-get install PACKAGE/unstable
Replace unstable with the repository that you wish to use.
With this command, apt-get installs the Unstable version of the package and tries to install the dependencies from Stable. This tactic does not always work, because some packages require a specific version of a dependency, but it will explain what the problem is. You will then need to fix the broken packages before you can install or upgrade anything else.
The second command structure example is:
apt-get -t unstable install PACKAGE
Again, replace Unstable with another repository if necessary.
With this structure, both the package and its dependencies are taken from Unstable. But whether this tactic works depends on how much effort the maintainer has put into the package. If they have only made sure that the package works for a specific set of circumstances, you are just as likely to have broken packages to fix as with the first tactic. No matter how you use pinning, some uncertainty always remains possible.
A Final Caution
If I sound overly cautious, the reason is that, like many Debian users, I have sometimes been tempted by one upgrade too many, condemning a system to dependency hell and hours of recovery.
Pinning can be a handy tool, which is why it remains popular. However, it is not a tool for beginners, nor one to use recklessly. After all, at this stage in Linux's development, having the latest upgrade matters less than it once did when the gaps in functionality were larger and more frequent.
Still, if you are like me, you will probably to be tempted to pin at some point. If so, then use it carefully, so that it helps rather handicaps you.
Infos
- Debian repositories: http://www.datamation.com/open-source/when-to-use-which-debian-linux-repository.html
Buy this article as PDF
(incl. VAT)
Buy Linux Magazine
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters
Support Our Work
Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.
News
-
Juno Computers Launches Another Linux Laptop
If you're looking for a powerhouse laptop that runs Ubuntu, the Juno Computers Neptune 17 v6 should be on your radar.
-
ZorinOS 17.1 Released, Includes Improved Windows App Support
If you need or desire to run Windows applications on Linux, there's one distribution intent on making that easier for you and its new release further improves that feature.
-
Linux Market Share Surpasses 4% for the First Time
Look out Windows and macOS, Linux is on the rise and has even topped ChromeOS to become the fourth most widely used OS around the globe.
-
KDE’s Plasma 6 Officially Available
KDE’s Plasma 6.0 "Megarelease" has happened, and it's brimming with new features, polish, and performance.
-
Latest Version of Tails Unleashed
Tails 6.0 is based on Debian 12 and includes GNOME 43.
-
KDE Announces New Slimbook V with Plenty of Power and KDE’s Plasma 6
If you're a fan of KDE Plasma, you'll be thrilled to hear they've announced a new Slimbook with an AMD CPU and the latest version of KDE Plasma desktop.
-
Monthly Sponsorship Includes Early Access to elementary OS 8
If you want to get a glimpse of what's in the pipeline for elementary OS 8, just set up a monthly sponsorship to help fund its continued existence.
-
DebConf24 to be Held in South Korea
Busan will be the location of the latest DebConf running July 28 through August 4
-
Fedora Unleashes Atomic Desktops
Fedora has combined its solid distribution with rpm-ostree system to make it possible to deliver a new family of Fedora spins, called Fedora Atomic Desktops.
-
Bootloader Vulnerability Affects Nearly All Linux Distributions
The developers of shim have released a version to fix numerous security flaws, including one that could enable remote control execution of malicious code under certain circumstances.