When we talk about Debian we must talk in the superlative. One of the reasons why Google and International Space Station are choosing Debian as their default Linux distribution is because it has (by far) the biggest package collection. At the time of writing this document, there are 61801 packages in Debian Sid (Unstable/Development distribution).
But as with many things in life, your greatest asset can be also your biggest liability—unless you take things under control. As an example, people usually complain how package versions in Debian “Stable” are too old, and they are spot on
right ignorant. The author of this document has never used Debian “Stable” outside of production and has solely relied on some of the ingenious mechanisms provided by Debian, which when properly configured can provide you with unlimited possibilities.
Pinning allows you to install and run package versions from other (Testing/Unstable/Experimental) Debian branches without having to upgrade the whole distribution to that particular branch.
You are running Debian 7.2 (Wheezy), and you want latest “libjmagick6-java” version (i.e: 6.6.9), however you only see the version which is present in Stable repository (6.2.6). When you look for the package on Debian packages, you can see that the version you want is present in Testing/Unstable.
You are running Debian 7.2 (Wheezy) and would want the latest GNOME Shell from Unstable/Experimental. Generally, you would want to turn to Backports. However, if the package you are looking for is not there, you might be out of luck. That is where APT Pinning steps up.
First you specify all the desired branches in your /etc/apt/source.list file. i.e:
# wheezy deb http://ftp.nl.debian.org/debian/ wheezy main contrib non-free deb-src http://ftp.nl.debian.org/debian/ wheezy main contrib non-free # wheezy Security deb http://security.debian.org/ wheezy/updates main contrib non-free deb-src http://security.debian.org/ wheezy/updates main contrib non-free # wheezy-updates, previously known as 'volatile' deb http://ftp.nl.debian.org/debian/ wheezy-updates main contrib non-free deb-src http://ftp.nl.debian.org/debian/ wheezy-updates main contrib non-free # wheezy-backports deb http://ftp.nl.debian.org/debian/ wheezy-backports main contrib non-free deb-src http://ftp.nl.debian.org/debian/ wheezy-backports main contrib non-free # jessie deb http://ftp.nl.debian.org/debian/ jessie main contrib non-free deb-src http://ftp.nl.debian.org/debian/ jessie main contrib non-free # jessie Security deb http://security.debian.org/ jessie/updates main contrib non-free deb-src http://security.debian.org/ jessie/updates main contrib non-free # sid deb http://ftp.nl.debian.org/debian/ sid main contrib non-free deb-src http://ftp.nl.debian.org/debian/ sid main contrib non-free # experimental deb http://ftp.nl.debian.org/debian/ experimental main contrib non-free deb-src http://ftp.nl.debian.org/debian/ experimental main contrib non-free
Then you’ll want to create a preferences file in /etc/apt/preferences i.e:
Package: * Pin: release a=testing Pin-Priority: 600 Package: * Pin: release a=stable Pin-Priority: 300 Package: * Pin: release a=unstable Pin-Priority: 200 Package: * Pin: release a=experimental Pin-Priority: 100
In this case, if we run lsb_release -a we will get the following information about the version of Debian that we are running:
Distributor ID: Debian Description: Debian GNU/Linux testing (jessie) Release: testing Codename: jessie
So what just happened here?
- In source.list file you declare which repositories you want to be available at your disposal
- in preferences file you define which branch you want to use based on the priority you gave to certain branch/es.
Rule of thumb: the higher the number it is, the higher the priority that branch will have. In this case “Jessie/Testing” is our base distribution, and when it comes to package installation, you prefer branches in following order:
So if you were about to install “libjmagick6-java” version from Sid/Unstable what would happen?
First you need to specify: apt-get -t sid install libjmagick6-java
The -t(–target-release) option specifies which branch you want to install your package from (i.e: -t sid/testing/experimental). So in this case, libjmagick6-java package binary will be pulled and installed from Sid. In the case where this package has dependencies, they will first be fetched from “Jessie/Testing” since that is the branch that has the highest priority. In the case where that specific package version is not available in this branch, APT will look for the same version in the branch which has the next highest priority, and so on, until the specified version is found in one of them.
Dissecting the preferences file
From what you have read so far, you will be able to install packages from other branches. However, with one single typo you will end up running Unstable system and you will not have a clue what happened.
Therefore it might help to explain some of the widely used options in preferences as well its definitions.
Package: * Pin: release a=testing Pin-Priority: 600
Asterisk (*), represents all packages names. Using wildcards will not work, thus specifying Package: ebuddy-* will not work.
Most widely used options are “Pin: release a=branch” or “Pin: release o=ebuddy“. Although another great example of using Pin field is specifying repository origin, i.e:
Pin: origin http://apt.ebuddy-office.net/ebuddy
A great example of using “Package” with combination of “Pin” field is specifying a particular package name. In other words, you want to keep a particular package at a particular version (not depending on which branch that version is).
Package: ebuddy-xms-cli Pin: version 0.5.34 Pin-Priority: 900
As previously mentioned, it is as simple as the higher the number is, the higher priority a particular branch has. However, there are caveats as well as additional features worth mentioning. From my personal experience, the highest priority number you should go with is <=1000. As in case you use 1001 for “Pin-Priority” it will enable downgrade disregarding any prior package priority. Going negative on other side will disable package version upgrade. Thus, if you give a package Pin-Priority of -10, any further updates of that package will be disabled. As previously noted, stay in rage of 100 to 900.
An important note regarding preferences file, you will get more desired/accurate results by using branches name stable/testing/unstable rather than codenames i.e: wheezy/jessie/sid
Different ways of being able to use apt-get -t option:
- apt-get -t branch install package_name
- apt-get install -t branch package_name
- apt-get install package_name/branch
Setting restrictions/pinning on repositories?
One of the most obvious examples is Backports repository, which once added is by default pinned to 100. So in order to install something from backports, you usually need to specify apt-get -t wheezy-backports install packaga_name. Otherwise even though the package name might have a higher version, it will not be made an installation candidate (which is the default behaviour in Debian).
So you might want to mimic this behaviour on your repositories. In our case we do this for repositories with ebuddy-* packages. The sole reason we do this is because we don’t want ebuddy-* packages to be upgraded during the distribution upgrade process, etc.
Adding “NotAutomatic: yes” field to your Release file will do the trick, however you won’t be able to just edit the current Release file within the repository you want to make these changes to. But there’s a hack which will enable you to do so, in this case it’s using the sed (unix stream editor) utility.
Running sed -i ‘/^Date: / aNotAutomatic: yes’ Release in directory where Release file is located will do the trick.
Since all of this seems like a lot of manual labor, our “update-deb” script which adds/removes packages to apt-ftparchive has been updated with this additional feature.
Thus adding “NotAutomatic: yes” field to your Release file is as simple as running “update-deb.sh -i -u -p all”
This is another field you might be interested in using in combination with “NotAutomatic: yes”. Since adding the previously noted field might have strict implications on your repository, you might want to have all updates from that repository automatically installed. This field will enable you to do so.
Using options described in this document will help you extend APT functionality to the maximum. I am certain that I have overlooked some of the options, as, in general, extending this goes into the same category as asking a submarine captain how deep his submarine can go. Not even he knows until he tries it.