| 1 | <!-- -*- mode: sgml; mode: fold -*- --> |
| 2 | <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V3.1//EN" [ |
| 3 | |
| 4 | <!ENTITY % aptent SYSTEM "apt.ent"> |
| 5 | %aptent; |
| 6 | |
| 7 | ]> |
| 8 | |
| 9 | <refentry> |
| 10 | &apt-docinfo; |
| 11 | |
| 12 | <refmeta> |
| 13 | <refentrytitle>apt_preferences</> |
| 14 | <manvolnum>5</> |
| 15 | </refmeta> |
| 16 | |
| 17 | <!-- Man page title --> |
| 18 | <refnamediv> |
| 19 | <refname>apt_preferences</> |
| 20 | <refpurpose>Preference control file for APT</> |
| 21 | </refnamediv> |
| 22 | |
| 23 | <RefSect1><Title>Description</> |
| 24 | <para> |
| 25 | The APT preferences file controls various aspects of the APT system. |
| 26 | It is meant to be user editable and manipulatable from software. The file |
| 27 | consists of a number of records formed like the dpkg status file, space |
| 28 | seperated sections of text with at the start of each line tags seperated |
| 29 | by a colon. It is stored in <filename>/etc/apt/preferences</>. |
| 30 | </RefSect1> |
| 31 | |
| 32 | <RefSect1><Title>Versioning</> |
| 33 | <para> |
| 34 | One purpose of the preferences file is to let the user select which version |
| 35 | of a package will be installed. This selection can be made in a number of |
| 36 | ways that fall into three categories, version, release and origin. |
| 37 | <para> |
| 38 | Selection by version can be done by exact match or prefix match. The format |
| 39 | is <literal/2.1.2/ or <literal/2.2*/ for a prefix match. Matching by prefix |
| 40 | can be used to ignore the <literal/r/ in the Debian release versioning, like |
| 41 | <literal/2.1r*/ or to ignore Debian specific revisions, <literal/1.1-*/. |
| 42 | When matching versions with a prefix the highest matching version will |
| 43 | always be picked. |
| 44 | <para> |
| 45 | Selection by release is more complicated and has three forms. The primary |
| 46 | purpose of release selections is to identify a set of packages that match |
| 47 | a specific vendor, or release (ie Debian 2.1). The first two forms are |
| 48 | shortcuts intended for quick command line use. If the first character of the |
| 49 | specification is a digit then it is considered to be a release version match, |
| 50 | otherwise a release label match. Specifications which contain equals are |
| 51 | full release data matches and are a comma seperated list of one letter keys |
| 52 | followed by an equals then by the string. Examples: |
| 53 | <informalexample><programlisting> |
| 54 | v=2.1*,o=Debian,c=main |
| 55 | l=Debian |
| 56 | a=stable |
| 57 | </programlisting></informalexample> |
| 58 | <para> |
| 59 | The data for these matches are taken from the <filename/Release/ files |
| 60 | that APT downloads during an <literal/update/. The available keys are: |
| 61 | <VariableList> |
| 62 | <VarListEntry><term>a= Archive</term> |
| 63 | <ListItem><Para> |
| 64 | This is the common name we give our archives, such as <literal/stable/ or |
| 65 | <literal/unstable/. The special name <literal/now/ is used to designate |
| 66 | the set of packages that are currently installed. |
| 67 | </VarListEntry> |
| 68 | |
| 69 | <VarListEntry><term>c= Component</term> |
| 70 | <ListItem><Para> |
| 71 | Referes to the sub-component of the archive, <literal/main/, |
| 72 | <literal/contrib/ etc. Component may be omitted if there are no |
| 73 | components for this archive. |
| 74 | </VarListEntry> |
| 75 | |
| 76 | <VarListEntry><term>v= Version</term> |
| 77 | <ListItem><Para> |
| 78 | This is a version string with the same properties as in the Packages file. |
| 79 | It represents the release level of the archive. Typical Debian release |
| 80 | numbers look like <literal/2.1r2/ with the r designating the release of |
| 81 | 2.1. New releases are limited to security updates and other important |
| 82 | changes. |
| 83 | </VarListEntry> |
| 84 | |
| 85 | <VarListEntry><term>o= Origin</term> |
| 86 | <ListItem><Para> |
| 87 | This specifies who is providing this archive. In the case of Debian the |
| 88 | string will read <literal/Debian/. Other providers may use their own |
| 89 | string. |
| 90 | </VarListEntry> |
| 91 | |
| 92 | <VarListEntry><term><term>l= Label</term> |
| 93 | <ListItem><Para> |
| 94 | This carries the encompassing name of the distribution. For Debian proper |
| 95 | this field reads <literal/Debian/. For derived distributions it should |
| 96 | contain their proper name. |
| 97 | </VarListEntry> |
| 98 | </VariableList> |
| 99 | <para> |
| 100 | The final selection method is by origin. This is simply the site name |
| 101 | of the originating package files. The empty string is used for file URIs. |
| 102 | <para> |
| 103 | Version selection, particularly the latter two methods, are used in many |
| 104 | different parts of APT, not just the preferences file. |
| 105 | </RefSect1> |
| 106 | |
| 107 | <RefSect1><Title>Candidate Version Policy</> |
| 108 | <para> |
| 109 | Internally APT maintains a list of all available versions for all packages. |
| 110 | If you place multiple releases or vendors in your &sources-list; file then |
| 111 | these features are available. By default APT selects the highest version |
| 112 | from all automatic sources. Some sources, such as |
| 113 | <filename>project/experimental</> are marked Not Automatic - these fall |
| 114 | to the bottom of the selection pile. |
| 115 | <para> |
| 116 | When deciding what version to use APT assigns a priority to each available |
| 117 | version of the package. It then does two things, first it selects |
| 118 | the highest priorty version that is newer than the installed version of the |
| 119 | package, then it selects the highest priority version that is older than |
| 120 | the installed version. Next, if the older versions have a priority greater |
| 121 | than 1000 they are compared with the priority of the upgrade set, the larger |
| 122 | becomes the selected result. Otherwise the downgrade versions are ignored |
| 123 | and the highest priority of the ugprade set is selected. |
| 124 | <para> |
| 125 | It is possible to think of the priorities in strata: |
| 126 | <VariableList> |
| 127 | <VarListEntry><term>above 1000</term> |
| 128 | <ListItem><Para> |
| 129 | Downgradable priorities |
| 130 | </VarListEntry> |
| 131 | |
| 132 | <VarListEntry><term>1000</term> |
| 133 | <ListItem><Para> |
| 134 | The downgrade prevention barrier |
| 135 | </VarListEntry> |
| 136 | |
| 137 | <VarListEntry><term>101 to 999</term> |
| 138 | <ListItem><Para> |
| 139 | Standard priorities. 990 is the priority set by the |
| 140 | <option/--target-release / &apt-get; option. 989 is the start for auto |
| 141 | priorities and 500 are all the default package files. |
| 142 | </VarListEntry> |
| 143 | |
| 144 | <VarListEntry><term>100</term> |
| 145 | <ListItem><Para> |
| 146 | The currently installed version |
| 147 | </VarListEntry> |
| 148 | |
| 149 | <VarListEntry><term>0 to 99</term> |
| 150 | <ListItem><Para> |
| 151 | Non automatic priorities. These are only used if the package |
| 152 | is not installed and there is no other version available. |
| 153 | </VarListEntry> |
| 154 | |
| 155 | <VarListEntry><term>less than 0</term> |
| 156 | <ListItem><Para> |
| 157 | The version is never selected. |
| 158 | </VarListEntry> |
| 159 | </VariableList> |
| 160 | <para> |
| 161 | Giving a pin a priority greater than 1000 will allow APT to downgrade |
| 162 | in order to get to that version. |
| 163 | <para> |
| 164 | Each package may be pinned to a specific version and each Packages file |
| 165 | has a priority for every package inside. The highest priority assigned |
| 166 | to a package is the one that is used. |
| 167 | <para> |
| 168 | A package pin looks like this: |
| 169 | <informalexample><programlisting> |
| 170 | Package: apt |
| 171 | Pin: version 0.4.0 |
| 172 | Pin-Priority: 1001 |
| 173 | </programlisting></informalexample> |
| 174 | The first line specifies the package, the second gives the Pin specification |
| 175 | and the last gives the priority of this pin. The first word of the pin |
| 176 | specification may be version, release or origin, the remainder of the field |
| 177 | is described in the Versioning section above. |
| 178 | <para> |
| 179 | A default pin is how the priorities of package files are set. Any number |
| 180 | of default pins may be specified, the first matching default will select |
| 181 | the priority of the package file. Only release or origin may be used in |
| 182 | the Pin specification since they match Packages files. |
| 183 | <informalexample><programlisting> |
| 184 | Package: * |
| 185 | Pin: release v=2.1* |
| 186 | Pin-Priority: 998 |
| 187 | </programlisting></informalexample> |
| 188 | <para> |
| 189 | If the Pin-Priority field is omitted then the priority defaults to 989 for |
| 190 | both cases. |
| 191 | |
| 192 | <RefSect2><title>Interesting Effects</> |
| 193 | <para> |
| 194 | Due to the downgrade prevention barrier at priority 1000 it is possible |
| 195 | that a lower priority version will be selected if the higher priority |
| 196 | would cause a downgrade. For instance, if package foo has versions |
| 197 | <literal/1.2/, <literal/1.1/ and <literal/1.0/ installed, with |
| 198 | <literal/1.1/ being the currently installed version and the priorities of |
| 199 | each version being 900, 100 and 950 repectively the winning version will be |
| 200 | <literal/1.2/. |
| 201 | <para> |
| 202 | In practice this is often desired. A user may use a default pin to |
| 203 | make the stable distribution the default and then use the |
| 204 | <option/--target-dist/ option with &apt-get; to select newer versions |
| 205 | from unstable. The packages that have been upgraded to unstable will |
| 206 | continue to follow the versions that are available in unstable since |
| 207 | the stable versions now fall below the downgrade prevention barrier. |
| 208 | <para> |
| 209 | If this is not desired then a default pin should be used to make unstable |
| 210 | have a priority less than 100. |
| 211 | <para> |
| 212 | Users of 3rd party add ons such as Helix GNOME can use this mechanism to |
| 213 | force the usage of Helix packages, or force the usage of Debian packages |
| 214 | by setting the priority of that source sufficiently high. It is even |
| 215 | possible to mass downgrade from one set of packages to another by |
| 216 | using a priority larger than 1000. |
| 217 | </RefSect2> |
| 218 | </RefSect1> |
| 219 | |
| 220 | <RefSect1><Title>See Also</> |
| 221 | <para> |
| 222 | &apt-cache; &apt-conf; |
| 223 | </RefSect1> |
| 224 | |
| 225 | &manbugs; |
| 226 | &manauthor; |
| 227 | |
| 228 | </refentry> |